步驟設定

逐步設定可讓連接器根據使用者提供的答案，動態填入連接器設定。舉例來說，在選取「州」下拉式選單後，填入「城市」下拉式選單。

需求條件

本指南假設您已熟悉社群連結器設定。如需複習，請參閱透過 getConfig 定義設定。

總覽

逐步設定是指 Data Studio 多次呼叫 getConfig()，而連接器每次都會傳回更多設定問題。每次呼叫 getConfig() 時，都會包含使用者對上次 getConfig() 回應的回答。只要您傳回含有 setIsSteppedConfig(true) 的回應，這個程序就會持續進行。

規範

設定 setIsSteppedConfig(true)，直到設定完成為止
只要設定 setIsSteppedConfig(true)，數據分析 就會重複呼叫 getConfig()。設定完成後，最終的 getConfig() 回應應會設定 setIsSteppedConfig(false)。
為決定後續問題的設定問題設定「isDynamic(true)」
如果使用者修改標示 isDynamic 的欄位，UI 中後續的設定項目就會清除，使用者必須設定所有後續步驟。這有助於確保使用者不會傳送無效的設定。
系統會透過 request.configParams 傳遞使用者提供的答案。

request.configParams 會是傳送至連接器的前 getConfig() 個要求 undefined。後續要求會將使用者提供的答案做為物件，以設定 ID 或 undefined 做為鍵，如果使用者未提供任何答案，則會以 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();
}

分支路徑

如果選取的「國家/地區」是「美國」，系統會詢問額外問題。

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