ステップ設定

ステップ設定により、ユーザーが指定した回答に基づいてコネクタ設定がコネクタに動的に取り込まれます。たとえば、「州」プルダウンが選択された後に「都市」プルダウンが表示されます。

要件

このガイドは、コミュニティ コネクタの設定に精通している方を対象としています。復習として、getConfig を使用して設定を定義するをご覧ください。

概要

ステップ構成では、Looker Studio が getConfig() を複数回呼び出し、コネクタが毎回追加の構成質問を返すようにします。getConfig() への各呼び出しには、最後の getConfig() レスポンスに対するユーザーの回答が含まれます。setIsSteppedConfig(true) を含むレスポンスを返す限り、このプロセスは継続されます。

ガイドライン

設定が完了するまで setIsSteppedConfig(true) を指定する
Looker Studio は、setIsSteppedConfig(true) が設定されている限り getConfig() を繰り返し呼び出します。構成が完了すると、最終的な getConfig() レスポンスで setIsSteppedConfig(false) が設定されます。
後続の質問を決定する設定質問に対して isDynamic(true) を設定する
isDynamic とマークされたフィールドがユーザーによって変更されると、それ以降の設定エントリは UI で消去されるため、ユーザーは後続のすべてのステップを設定する必要があります。これにより、ユーザーが無効な構成を送信しないようにできます。
ユーザー指定の回答は 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();
}