分步配置

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

要求

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

概览

分步配置由 Looker Studio 调用 getConfig() 多个方法组成 而您的连接器每次都会返回更多配置问题。每个 对 getConfig() 的调用将包含用户对上一个 getConfig() 的回答 响应。只要您使用 setIsSteppedConfig(true)

指南

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

request.configParamsgetConfig()的价格为 undefined 向连接器发出请求后续请求将包括 用户提供的回答作为由配置 ID 或 如果用户未提供任何答案,则为 undefined

示例:

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

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

配置无法更改

如果用户之前询问过某个配置问题,则它应针对所有后续调用显示。例如,如果系统询问了配置问题 A 第一次调用 getConfig() 时,所有将来都应添加 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();
}