Stufenkonfiguration

Bei der gestaffelten Konfiguration wird die Konfiguration eines Connectors anhand der von Nutzern bereitgestellten Antworten dynamisch ausgefüllt. Sie können z. B. das Drop-down-Menü „City“ ausfüllen, nachdem das Drop-down-Menü „State“ ausgewählt wurde.

Voraussetzungen

In diesem Leitfaden wird davon ausgegangen, dass Sie bereits mit Community-Connector-Konfigurationen vertraut sind. Frischen Sie Ihr Wissen unter Definieren der Konfiguration über getConfig auf.

Überblick

Bei der gestaffelten Konfiguration wird getConfig() mehrmals von Looker Studio aufgerufen, wobei der Connector jedes Mal weitere Konfigurationsfragen zurückgibt. Jeder Aufruf von getConfig() enthält die Antworten des Nutzers auf die letzte getConfig()-Antwort. Dieser Vorgang wird fortgesetzt, wenn Sie eine Antwort mit setIsSteppedConfig(true) zurückgeben.

Richtlinien

Legen Sie setIsSteppedConfig(true) fest, bis die Konfiguration abgeschlossen ist

getConfig() wird in Looker Studio wiederholt aufgerufen, solange setIsSteppedConfig(true) festgelegt ist.Sobald die Konfiguration abgeschlossen ist, sollte in der endgültigen getConfig()-Antwort setIsSteppedConfig(false) festgelegt werden.

Legen Sie isDynamic(true) für Konfigurationsfragen fest, die spätere Fragen bestimmen.

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

Von Nutzern bereitgestellte Antworten werden per request.configParams weitergegeben.

request.configParams ist für die erste getConfig()-Anfrage an den Connector undefined. Nachfolgende Anfragen enthalten die vom Nutzer bereitgestellten Antworten als Objekt, das durch die Konfigurations-IDs oder undefined verschlüsselt wird, wenn der Nutzer keine Antworten bereitstellt.

Beispiel:

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

Konfigurationen sind additiv

Neue Konfigurationsfragen sollten nach vorhandenen Fragen hinzugefügt werden.

Konfigurationen können nicht geändert werden

Wenn zuvor eine Konfigurationsfrage gestellt wurde, sollte sie für alle nachfolgenden Aufrufe 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 derselben configParams sollten dieselbe Konfiguration zurückgeben.

Dynamische Parameter können nicht überschrieben werden

In Looker Studio können Parameter für dynamische Konfigurationen nicht überschrieben werden.

Beispielkonfigurationen

Dynamische Drop-down-Menüs

Mit dieser ersten Frage wird der Nutzer aufgefordert, einen Bundesstaat auszuwählen. Dann wird dynamisch ein Drop-down-Menü für die Stadt eingeblendet, das auf dem ausgewählten Bundesstaat basiert.

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

Verzweigte Pfade

Es wird eine zusätzliche Frage gestellt, wenn als „Land“ „USA“ ausgewählt wurde.

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