Konfiguracja krokowa

Konfiguracja krokowa umożliwia dynamiczne wypełnianie konfiguracji złącza na podstawie odpowiedzi podanych przez użytkownika. Na przykład wypełnianie menu „Miasto” po wybraniu menu „Stan”.

Wymagania

W tym przewodniku zakładamy, że znasz już konfiguracje łącznika społeczności. Przypomnij sobie, jak definiować konfigurację za pomocą funkcji getConfig.

Przegląd

Konfiguracja krokowa polega na tym, że Studio danych wywołuje getConfig() wiele razy, a łącznik za każdym razem zwraca więcej pytań konfiguracyjnych. Każde wywołanie funkcji getConfig() będzie zawierać odpowiedzi użytkownika na ostatnią odpowiedź getConfig(). Ten proces jest kontynuowany, dopóki zwracasz odpowiedź z setIsSteppedConfig(true).

Wytyczne

Ustaw setIsSteppedConfig(true), dopóki konfiguracja nie zostanie ukończona.

Studio danych będzie wielokrotnie wywoływać getConfig(), dopóki ustawiona jest wartość setIsSteppedConfig(true).Po zakończeniu konfiguracji ostatnia odpowiedź getConfig() powinna ustawić wartość setIsSteppedConfig(false).

Ustaw isDynamic(true) w przypadku pytań konfiguracyjnych, które określają późniejsze pytania.

Jeśli użytkownik zmodyfikuje pole oznaczone symbolem isDynamic, kolejne wpisy konfiguracji zostaną wyczyszczone w interfejsie, a użytkownik będzie musiał skonfigurować wszystkie kolejne kroki. Dzięki temu użytkownicy nie będą wysyłać Ci nieprawidłowych konfiguracji.

Odpowiedzi użytkowników będą przekazywane za pomocą metody request.configParams.

request.configParams będzie wynosić undefined w przypadku pierwszego żądania wysłanego do łącznika.getConfig() Kolejne żądania będą zawierać odpowiedzi użytkownika jako obiekt z kluczami w postaci identyfikatorów konfiguracji lub undefined, jeśli użytkownik nie poda żadnych odpowiedzi.

Przykład:

{
  state: 'CA',
  city: 'mountain_view'
}

Konfiguracje się sumują

Nowe pytania konfiguracyjne należy dodawać po istniejących.

Nie można zmieniać konfiguracji

Jeśli pytanie konfiguracyjne zostało zadane wcześniej, powinno być obecne we wszystkich kolejnych wywołaniach. Jeśli na przykład w pierwszym wywołaniu funkcji getConfig() zadano pytanie konfiguracyjne A, odpowiedź A powinna być uwzględniana we wszystkich kolejnych odpowiedziach.

Konfiguracje są idempotentne

Wywołania funkcji getConfig() z tym samym parametrem configParams powinny zwracać tę samą konfigurację.

Parametry dynamiczne nie mogą być zastępowane

Studio danych nie zezwala na zastępowanie parametrów konfiguracji dynamicznej.

Przykładowe konfiguracje

Dynamiczne menu

Pierwsze pytanie prosi użytkownika o wybranie stanu, a następnie dynamicznie wyświetla menu miast w zależności od wybranego stanu.

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

Ścieżki rozgałęziające się

Jeśli wybranym „Krajem” są „Stany Zjednoczone”, pojawi się dodatkowe pytanie.

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