Configuración escalonada

La configuración por pasos permite que un conector complete dinámicamente la configuración del conector en función de las respuestas proporcionadas por el usuario. Por ejemplo, completar un menú desplegable "Ciudad" después de seleccionar un menú desplegable "Estado".

Requisitos

En esta guía, se supone que ya estás familiarizado con las configuraciones de Community Connector. Consulta Cómo definir la configuración a través de getConfig para obtener un repaso.

Descripción general

La configuración por pasos consiste en que Data Studio llama a getConfig() varias veces y que el conector muestra más preguntas de configuración cada vez. Cada llamada a getConfig() incluirá las respuestas del usuario a la última respuesta de getConfig(). Este proceso continúa siempre y cuando muestres una respuesta con setIsSteppedConfig(true).

Lineamientos

Establece setIsSteppedConfig(true) hasta que se complete la configuración.

Data Studio llamará a getConfig() de forma repetida siempre y cuando se establezca setIsSteppedConfig(true).Una vez que se complete la configuración, la respuesta final de getConfig() debe establecer setIsSteppedConfig(false).

Establece isDynamic(true) para las preguntas de configuración que determinan preguntas posteriores.

Si el usuario modifica un campo marcado como isDynamic, se borrarán las entradas de configuración posteriores en la IU, y el usuario deberá configurar todos los pasos posteriores. Esto ayuda a garantizar que los usuarios no te envíen una configuración no válida.

Las respuestas proporcionadas por el usuario se pasarán a través de request.configParams.

request.configParams será undefined para la primera solicitud de getConfig() a tu conector. Las solicitudes posteriores incluirán las respuestas proporcionadas por el usuario como un objeto con clave por los IDs de configuración o undefined si el usuario no proporciona ninguna respuesta.

Ejemplo:

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

Las configuraciones son aditivas.

Las nuevas preguntas de configuración deben agregarse después de las existentes.

Las configuraciones no se pueden mutar.

Si se hizo una pregunta de configuración anteriormente, debe estar presente en todas las llamadas posteriores. Por ejemplo, si se hizo la pregunta de configuración A en la primera llamada a getConfig(), A debe incluirse en todas las respuestas futuras.

Las configuraciones son idempotentes.

Las llamadas a getConfig() con el mismo configParams deben mostrar la misma configuración.

Los parámetros dinámicos no se pueden anular.

Data Studio no permitirá que se anulen los parámetros de configuración dinámicos overridden.

Configuración de ejemplo

Menús desplegables dinámicos

Esta primera pregunta le solicita al usuario que seleccione un estado y, luego, proporciona dinámicamente un menú desplegable de ciudades en función del estado seleccionado.

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

Rutas de bifurcación

Esto hará una pregunta adicional si el "País" seleccionado es "EE.UU.".

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