步驟設定

步驟設定可讓連接器根據使用者提供的答案動態填入連接器設定。例如在已選取「狀態」下拉式選單後填入「城市」下拉式選單。

需求條件

本指南假設您已熟悉社群連接器設定。詳情請參閱「透過 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();
}

分支版本

如果所選「國家/地區」為「美國」，就會提出另一個問題。

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