Configuração por etapas

Na configuração por etapas, o conector preenche dinamicamente a própria configuração com base nas respostas fornecidas pelo usuário. Por exemplo, as informações da lista suspensa "Cidade" são preenchidas depois que "Estado" é selecionado.

Requisitos

Para acompanhar o conteúdo deste guia, você precisa conhecer as configurações do conector da comunidade. Consulte Definir a configuração via getConfig se precisar de uma revisão.

Informações gerais

Na configuração por etapas, o Looker Studio chama getConfig() várias vezes, e seu conector retorna mais perguntas de configuração a cada vez. Cada chamada para getConfig() vai incluir as respostas do usuário ao último getConfig(). Esse processo vai continuar enquanto você retornar uma resposta com setIsSteppedConfig(true).

Diretrizes

Defina setIsSteppedConfig(true) até que a configuração seja concluída

O Looker Studio vai chamar getConfig() repetidamente, desde que setIsSteppedConfig(true) seja definido.Depois que a configuração for concluída, a resposta final de getConfig() definirá setIsSteppedConfig(false).

Defina isDynamic(true) para perguntas de configuração que determinam as próximas questões

Se um campo marcado como isDynamic for modificado pelo usuário, as entradas de configuração subsequentes serão removidas, e o usuário precisará configurar todas as etapas seguintes. Isso ajuda a garantir que os usuários não enviem uma configuração inválida.

As respostas fornecidas pelo usuário serão transmitidas por request.configParams.

O valor request.configParams será undefined para a primeira solicitação getConfig() feita ao seu conector. As solicitações seguintes vão incluir as respostas fornecidas pelo usuário como um objeto codificado pelos IDs de configuração, ou undefined se o usuário não fornecer respostas.

Exemplos

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

As configurações são acumulativas

Novas questões de configuração serão adicionadas após as existentes.

Não é possível alterar as configurações

Se uma pergunta de configuração já foi feita, ela precisa estar presente em todas as chamadas seguintes. Por exemplo, se a pergunta de configuração A tiver sido feita na primeira chamada para getConfig(), A precisará ser incluída em todas as respostas futuras.

As configurações são idempotentes

As chamadas para getConfig() com o mesmo configParams precisam retornar a mesma configuração.

Os parâmetros dinâmicos não podem ser modificáveis

O Looker Studio não permitirá que os parâmetros de configuração dinâmicos sejam substituídos.

Exemplos de configurações

Listas suspensas dinâmicas

Na primeira pergunta, o usuário precisa selecionar um estado e, em seguida, será exibida uma lista suspensa dinâmica de cidades com base no estado em questão.

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

Caminhos de ramificação

Uma pergunta adicional será feita se o "País" selecionado for "EUA".

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