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.

Como usar a configuração por etapas

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.

Visão geral

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

Diretrizes

Defina setIsSteppedConfig(true) até que a configuração seja concluída
O Data Studio chamará getConfig() várias vezes, desde que setIsSteppedConfig(true) seja definido. Após o término da configuração, 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.

request.configParams terá o valor undefined na primeira solicitação getConfig() feita ao seu conector. Os pedidos seguintes incluirão as respostas fornecidas pelo usuário como um objeto inserido pelos IDs de configuração, ou undefined se o usuário não enviar respostas.

Exemplo:

{
      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 A apareceu 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 Data Studio não permitirá que os parâmetros de configuração dinâmicos sejam modificados.

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