分步配置

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

要求

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

概览

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

指南

设置 setIsSteppedConfig(true)，直到配置完成

只要设置了 setIsSteppedConfig(true)，Looker Studio 就会重复调用 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() 应返回相同的配置。

动态参数不可替换

Looker Studio 不允许替换动态配置参数。

示例配置

动态下拉列表

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

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();
}