Пошаговая конфигурация

Пошаговая настройка позволяет коннектору динамически заполнять конфигурацию на основе ответов пользователя. Например, заполнение выпадающего списка «Город» после выбора пункта в выпадающем списке «Штат».

Требования

В этом руководстве предполагается, что вы уже знакомы с настройками Community Connector. Для повторного ознакомления см. раздел «Определение конфигурации через getConfig» .

Обзор

Пошаговая настройка состоит в том, что Data Studio вызывает getConfig() несколько раз, и ваш коннектор каждый раз возвращает новые вопросы конфигурации. Каждый вызов getConfig() будет включать ответы пользователя на последний запрос getConfig() . Этот процесс продолжается до тех пор, пока вы возвращаете ответ с setIsSteppedConfig(true) .

Руководящие принципы

Установите значение setIsSteppedConfig(true) до завершения настройки.

Data Studio будет многократно вызывать getConfig() до тех пор, пока установлено значение setIsSteppedConfig(true) После завершения настройки окончательный ответ getConfig() должен установить значение setIsSteppedConfig(false) .

Установите isDynamic(true) для вопросов конфигурации, которые определяют последующие вопросы.

Если пользователь изменяет поле с пометкой isDynamic , последующие записи конфигурации в пользовательском интерфейсе будут очищены, и пользователю потребуется выполнить все последующие шаги заново. Это помогает гарантировать, что пользователи не отправят вам некорректную конфигурацию.

Ответы, предоставленные пользователем, будут передаваться через request.configParams .

В первом запросе getConfig() к вашему коннектору значение request.configParams будет undefined . Последующие запросы будут включать предоставленные пользователем ответы в виде объекта, ключами которого являются идентификаторы конфигурации, или undefined если пользователь не предоставит никаких ответов.

Пример:

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

Конфигурации являются аддитивными.

Новые вопросы по настройке следует добавлять после существующих.

Конфигурации нельзя изменять.

Если ранее был задан вопрос о конфигурации, он должен присутствовать во всех последующих вызовах. Например, если вопрос о конфигурации A был задан при первом вызове функции getConfig() , то A должен быть включен во все последующие ответы.

Конфигурации идемпотентны.

Вызовы метода getConfig() с одинаковыми configParams должны возвращать одну и ту же конфигурацию.

Динамические параметры нельзя переопределить.

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