分步配置

借助分步配置,连接器可以根据用户提供的回答动态填充连接器配置。例如,在用户选择“州”下拉列表后填充“城市”下拉列表。

使用分步配置

要求

本指南假设您已熟悉社区连接器配置。如需回顾相关知识,请参阅通过 getConfig 定义配置

概览

分步配置涉及数据洞察多次调用 getConfig(),而您的连接器每次都返回更多配置问题。对 getConfig() 的每次调用都将包括用户对上一次 getConfig() 响应的回答。只要您通过 setIsSteppedConfig(true) 返回响应,该过程就会继续。

指南

设置 setIsSteppedConfig(true),直到配置完成
只要设置了 setIsSteppedConfig(true),数据洞察就会重复调用 getConfig()。配置完成后,最后的 getConfig() 响应应设置 setIsSteppedConfig(false)
为可用于确定后续问题的配置问题设置 isDynamic(true)
如果用户修改了标记为 isDynamic 的字段,则系统会在界面中清除后续配置条目,且用户需要配置所有后续步骤。这有助于确保用户不会向您发送无效配置。
用户提供的回答将通过 request.configParams 传递。

对于向连接器发出的第一个 getConfig() 请求,request.configParams 将是 undefined。后续请求会包括用户提供的回答,并将其作为一个对象(由配置 ID 键控);如果用户未提供任何回答,则为 undefined

示例:

{
      state: 'CA',
      city: 'mountain_view'
    }
    
配置是累加的

新的配置问题应添加到现有配置问题之后。

配置无法更改

如果用户之前询问过某个配置问题,则它应针对所有后续调用显示。例如,如果在第一次调用 getConfig() 时询问了配置问题 A,则所有后续响应都应包含问题 A

配置是幂等的

使用同一 configParams 调用 getConfig() 应返回相同的配置。

动态参数不可替换

数据洞察禁止替换动态配置参数。

示例配置

动态下拉列表

第一个问题提示用户选择一个州,然后它根据用户所选的州动态提供一个“城市”下拉列表。

var cc = DataStudioApp.createCommunityConnector();

    function optionsForState(state) {
      switch (state) {
        case "IL": {
          return [["Chicago", "chicago"], ["Springfield", "springfield"]];
        }
        case "CA": {
          return [["Mountain View", "mountain_view"], ["Los Angeles", "los_angeles"]];
        }
        default: {
          cc.newUserError()
              .setText('You must either select "IL" or "CA"')
              .throwException();
        }
      }
    }

    function getConfig(request) {
      var configParams = request.configParams;
      var isFirstRequest = configParams === undefined;
      var config = cc.getConfig();
      if (isFirstRequest) {
        config.setIsSteppedConfig(true);
      }

      config.newSelectSingle()
          .setId("state")
          .setName("State")
      // Set isDynamic to true so any changes to State will clear the city
      // selections.
          .setIsDynamic(true)
          .addOption(config.newOptionBuilder().setLabel("Illinois").setValue("IL"))
          .addOption(config.newOptionBuilder().setLabel("California").setValue("CA"));

      if (!isFirstRequest) {
        var city = config.newSelectSingle()
            .setId("city")
            .setName("City");
        var cityOptions = optionsForState(configParams.state);
        cityOptions.forEach(function(labelAndValue) {
          var cityLabel = labelAndValue[0];
          var cityValue = labelAndValue[1];
          city.addOption(config.newOptionBuilder().setLabel(cityLabel).setValue(cityValue));
        });
      }
      return config.build();
    }
    

分支路径

如果用户选择的“国家/地区”是“USA”,则系统会再提问一个问题。

var cc = DataStudioApp.createCommunityConnector();

    function getConfig(request) {
      var configParams = request.configParams;
      var isFirstRequest = configParams === undefined;
      var config = cc.getConfig();
      if (isFirstRequest) {
        config.setIsSteppedConfig(true);
      }

      config
          .newSelectSingle()
          .setId('country')
          .setName('Country')
      // Set isDynamic to true so any changes to Country will clear the state
      // selections.
          .setIsDynamic(true)
          .addOption(config.newOptionBuilder().setLabel('United States').setValue('USA'))
          .addOption(config.newOptionBuilder().setLabel('Canada').setValue('CA'));

      if (!isFirstRequest) {
        // validate a valid value was selected for configParams.country
        if (configParams.country === undefined) {
          cc.newUserError().setText('You must choose a country.').throwException();
        }
        switch (configParams.country) {
          case 'USA': {
            config
                .newSelectSingle()
                .setId('state')
                .setName('State')
                .addOption(config.newOptionBuilder().setLabel('New York').setValue('NY'))
                .addOption(config.newOptionBuilder().setLabel('Calfornia').setValue('CA'));
            break;
          }
          case 'CA': {
            // No additional configuration is needed for Canada.
            break;
          }
          default: {
            cc.newUserError()
                .setText('You must either select "CA" or "USA"')
                .throwException();
          }
        }
      }
      return config.build();
    }