단계별 구성

단계별 구성을 사용하면 커넥터가 사용자 제공 답변을 기반으로 커넥터 구성을 동적으로 채울 수 있습니다. 예를 들어 '주' 드롭다운이 선택된 후 '도시' 드롭다운을 채웁니다.

요구사항

이 가이드에서는 커뮤니티 커넥터 구성에 이미 익숙하다고 가정합니다. 새로고침은 getConfig를 통한 구성 정의를 참조하세요.

개요

단계별 구성은 데이터 스튜디오가 getConfig()를 여러 번 호출하고 커넥터가 매번 더 많은 구성 질문을 반환하는 것으로 구성됩니다. getConfig()를 호출할 때마다 마지막 getConfig() 응답에 대한 사용자의 답변이 포함됩니다. setIsSteppedConfig(true)로 응답을 반환하는 한 이 프로세스가 계속됩니다.

가이드라인

구성이 완료될 때까지 setIsSteppedConfig(true) 설정
setIsSteppedConfig(true)가 설정되어 있는 한 데이터 스튜디오는 getConfig()를 반복적으로 호출합니다.구성이 완료되면 최종 getConfig() 응답에서 setIsSteppedConfig(false)를 설정해야 합니다.
나중에 질문을 결정하는 구성 질문에 isDynamic(true) 설정
isDynamic으로 표시된 필드가 사용자에 의해 수정되면 후속 구성 항목이 UI에서 삭제되고 사용자는 후속 단계를 모두 구성해야 합니다. 이렇게 하면 사용자가 잘못된 구성을 보내지 않도록 할 수 있습니다.
사용자 제공 답변은 request.configParams를 통해 전달됩니다.

커넥터에 대한 첫 번째 getConfig() 요청의 경우 request.configParams가 undefined입니다. 후속 요청에는 구성 ID를 키로 하는 객체로 사용자 제공 답변이 포함되거나 사용자가 답변을 제공하지 않는 경우 undefined가 포함됩니다.

예:

{
  state: 'CA',
  city: 'mountain_view'
}
구성은 추가적임

새 구성 질문은 기존 질문 뒤에 추가해야 합니다.

구성은 변경할 수 없음

구성 질문이 이전에 요청된 경우 모든 후속 호출에 있어야 합니다. 예를 들어 getConfig()의 첫 번째 호출에서 구성 질문 A 가 요청된 경우 A 는 모든 향후 응답에 포함되어야 합니다.

구성은 멱등원임

동일한 configParams로 getConfig()를 호출하면 동일한 구성이 반환되어야 합니다.

동적 매개변수는 재정의할 수 없음

데이터 스튜디오에서는 동적 구성 매개변수를 재정의할 수 없습니다.

구성 예시

동적 드롭다운

이 첫 번째 질문은 사용자에게 주를 선택하라는 메시지를 표시한 다음 선택한 주를 기반으로 도시 드롭다운을 동적으로 제공합니다.

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