La configuración escalonada permite que un conector rellene dinámicamente su configuración en función de las respuestas proporcionadas por los usuarios. Por ejemplo, puede rellenar el menú desplegable de ciudad después de que el usuario seleccione una opción en el menú desplegable de estado.
Requisitos
En esta guía se da por hecho que estás familiarizado con las configuraciones de los conectores comunitarios. Si quieres revisar la información relacionada, consulta Definir la configuración con getConfig.
Introducción
En la configuración escalonada, Data Studio llama a getConfig()
varias veces y tu conector devuelve 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 persiste siempre y cuando devuelvas una respuesta con setIsSteppedConfig(true)
.
Directrices
- Define
setIsSteppedConfig(true)
hasta que se complete la configuración - Data Studio llamará repetidamente a
getConfig()
siempre y cuandosetIsSteppedConfig(true)
esté definido. Cuando se haya terminado la configuración, la respuesta final degetConfig()
debería definirsetIsSteppedConfig(false)
. - Define
isDynamic(true)
para las preguntas de configuración que determinan las preguntas posteriores - Si el usuario modifica un campo marcado como
isDynamic
, las entradas de configuración posteriores se borrarán en la UI y el usuario deberá configurar todos los pasos posteriores. De esta manera, te aseguras de que los usuarios solo te envíen configuraciones válidas. - Las respuestas proporcionadas por los usuarios se transferirán a través de
request.configParams
. request.configParams
seráundefined
en la primera solicitudgetConfig()
a tu conector. Las solicitudes posteriores incluirán las respuestas proporcionadas por el usuario como un objeto con la clave de los ID de configuración, o el valorundefined
si el usuario no proporciona ninguna respuesta.Ejemplo:
{ state: 'CA', city: 'mountain_view' }
- Las configuraciones son acumulativas
Las preguntas de configuración nuevas deben añadirse a las que ya existen.
- No es posible alterar las configuraciones
Si se ha hecho una pregunta de configuración anteriormente, debe estar presente en todas las llamadas posteriores. Por ejemplo, si se ha hecho la pregunta de configuración A en la primera llamada a
getConfig()
, A debería incluirse en todas las respuestas posteriores.- Las configuraciones son idempotentes
Las llamadas a
getConfig()
con el mismoconfigParams
deberían devolver la misma configuración.- Los parámetros dinámicos no pueden ser anulables
Data Studio no permite que se anulen los parámetros de configuración dinámicos.
Configuraciones de ejemplo
Menús desplegables dinámicos
En esta primera pregunta se solicita al usuario que elija un estado y, a continuación, se proporciona dinámicamente un menú desplegable de ciudad 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 encabezado
Se hará otra pregunta si el país ("Country") seleccionado es EE. UU. ("USA").
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();
}