Stufenkonfiguration

Bei der schrittweisen Konfiguration kann ein Connector die Connectorkonfiguration dynamisch anhand der Antworten des Nutzers ausfüllen. Beispiel: Wenn ein Drop-down-Menü für „Bundesland“ ausgewählt wurde, wird ein Drop-down-Menü für „Stadt“ ausgefüllt.

Voraussetzungen

In dieser Anleitung wird davon ausgegangen, dass Sie bereits mit Community Connector-Konfigurationen vertraut sind. Eine Auffrischung finden Sie unter Konfiguration über getConfig definieren.

Übersicht

Bei der schrittweisen Konfiguration ruft Data Studio getConfig() mehrmals auf und Ihr Connector gibt jedes Mal weitere Konfigurationsfragen zurück. Jeder Aufruf von getConfig() enthält die Antworten des Nutzers auf die letzte getConfig()-Antwort. Dieser Vorgang wird so lange fortgesetzt, bis Sie eine Antwort mit setIsSteppedConfig(true) zurückgeben.

Richtlinien

setIsSteppedConfig(true) festlegen, bis die Konfiguration abgeschlossen ist

Data Studio ruft getConfig() so lange wiederholt auf, bis setIsSteppedConfig(true) festgelegt ist.Nach Abschluss der Konfiguration sollte in der letzten getConfig()-Antwort setIsSteppedConfig(false) festgelegt werden.

isDynamic(true) für Konfigurationsfragen festlegen, die spätere Fragen bestimmen

Wenn ein Feld mit isDynamic vom Nutzer geändert wird, werden nachfolgende Konfigurationseinträge in der Benutzeroberfläche gelöscht und der Nutzer muss alle nachfolgenden Schritte konfigurieren. So wird verhindert, dass Nutzer Ihnen eine ungültige Konfiguration senden.

Die vom Nutzer angegebenen Antworten werden über request.configParams übergeben.

request.configParams ist für die erste getConfig()-Anfrage an Ihren Connector undefined. Nachfolgende Anfragen enthalten die vom Nutzer angegebenen Antworten als Objekt, das nach den Konfigurations-IDs oder undefined strukturiert ist, wenn der Nutzer keine Antworten gibt.

Beispiel:

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

Konfigurationen sind additiv

Neue Konfigurationsfragen sollten nach den vorhandenen hinzugefügt werden.

Konfigurationen können nicht geändert werden

Wenn eine Konfigurationsfrage bereits gestellt wurde, sollte sie bei allen nachfolgenden Aufrufen vorhanden sein. Wenn beispielsweise die Konfigurationsfrage A im ersten Aufruf von getConfig() gestellt wurde, sollte A in allen zukünftigen Antworten enthalten sein.

Konfigurationen sind idempotent

Aufrufe von getConfig() mit denselben configParams sollten dieselbe Konfiguration zurückgeben.

Dynamische Parameter können nicht überschrieben werden

In Data Studio können dynamische Konfigurationsparameter nicht überschrieben werden.

Beispielkonfigurationen

Dynamische Drop-down-Menüs

In dieser ersten Frage wird der Nutzer aufgefordert, ein Bundesland auszuwählen. Anschließend wird dynamisch ein Drop-down-Menü für die Stadt basierend auf dem ausgewählten Bundesland bereitgestellt.

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

Verzweigungspfade

Wenn das ausgewählte Land „USA“ ist, wird eine zusätzliche Frage gestellt.

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