借助分步配置,连接器可以根据用户提供的回答动态填充连接器配置。例如,在用户选择“州”下拉列表后填充“城市”下拉列表。
要求
本指南假设您已熟悉社区连接器配置。如需回顾相关知识,请参阅通过 getConfig 定义配置。
概览
分步配置涉及 Looker Studio 多次调用 getConfig()
,而您的连接器每次都返回更多配置问题。对 getConfig()
的每次调用都将包含用户对上一次 getConfig()
响应的回答。只要您通过 setIsSteppedConfig(true)
返回响应,该过程就会继续。
指南
- 设置
setIsSteppedConfig(true)
,直到配置完成 - 只要设置了
setIsSteppedConfig(true)
,Looker Studio 就会重复调用getConfig()
。配置完成后,最终的getConfig()
响应应设置setIsSteppedConfig(false)
。 - 为可用于确定后续问题的配置问题设置
isDynamic(true)
- 如果用户修改了标记为
isDynamic
的字段,则系统会在界面中清除后续配置条目,并且用户需要配置所有后续步骤。这有助于确保用户不会向您发送无效配置。 - 用户提供的回答将通过
request.configParams
传递。 对于发送到连接器的第一个
getConfig()
请求,request.configParams
将为undefined
。后续请求将包含用户提供的答案作为对象,由配置 ID 键控,如果用户未提供任何答案,则包含undefined
。例如:
{ state: 'CA', city: 'mountain_view' }
- 配置是累加的
新的配置问题应添加到现有配置问题之后。
- 配置无法更改
如果用户之前询问过某个配置问题,则它应针对所有后续调用显示。例如,如果在第一次调用
getConfig()
时询问了配置问题 A,则所有后续响应都应包含问题 A。- 配置是幂等的
使用同一
configParams
调用getConfig()
应返回相同的配置。- 动态参数不可替换
Looker Studio 不允许替换动态配置参数。
示例配置
动态下拉列表
第一个问题提示用户选择一个州,然后它根据用户所选的州动态提供一个“城市”下拉列表。
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();
}
分支路径
如果用户选择的“国家/地区”是“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();
}