步驟設定可讓連接器根據使用者提供的答案動態填入連接器設定。例如在已選取「狀態」下拉式選單後填入「城市」下拉式選單。
需求條件
本指南假設您已熟悉社群連接器設定。詳情請參閱「透過 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();
}
分支版本
如果所選「國家/地區」為「美國」,就會提出另一個問題。
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();
}