Adımlı Yapılandırma

Adımlı yapılandırma, bağlayıcının kullanıcı tarafından sağlanan yanıtlara göre bağlayıcı yapılandırmasını dinamik olarak doldurmasına olanak tanır. Örneğin, "Eyalet" açılır listesi seçildikten sonra "Şehir" açılır listesini doldurma.

Şartlar

Bu rehberde, Topluluk Bağlayıcı yapılandırmaları hakkında bilgi sahibi olduğunuz varsayılır. Bilgilerinizi tazelemek için Yapılandırmayı getConfig aracılığıyla tanımlama başlıklı makaleye göz atın.

Genel Bakış

Adımlı yapılandırma, Data Studio'nun getConfig() birden fazla kez çağrılmasından ve bağlayıcınızın her seferinde daha fazla yapılandırma sorusu döndürmesinden oluşur. getConfig() işlevine yapılan her çağrı, kullanıcının son getConfig() yanıtına verdiği cevapları içerir. Bu süreç, setIsSteppedConfig(true) ile yanıt döndürdüğünüz sürece devam eder.

Yönergeler

Yapılandırma tamamlanana kadar setIsSteppedConfig(true)

Data Studio, setIsSteppedConfig(true) ayarlandığı sürece getConfig() işlevini tekrar tekrar çağırır.Yapılandırma tamamlandıktan sonra son getConfig() yanıtı setIsSteppedConfig(false) değerini ayarlamalıdır.

Daha sonraki soruları belirleyen yapılandırma soruları için isDynamic(true) ayarlama

isDynamic ile işaretlenmiş bir alan kullanıcı tarafından değiştirilirse sonraki yapılandırma girişleri kullanıcı arayüzünde temizlenir ve kullanıcının sonraki tüm adımları yapılandırması gerekir. Bu sayede kullanıcıların size geçersiz bir yapılandırma göndermemesi sağlanır.

Kullanıcı tarafından sağlanan yanıtlar request.configParams üzerinden iletilir.

request.configParams, bağlayıcınıza yapılan ilk getConfig() istek için undefined olacak. Sonraki istekler, kullanıcı tarafından sağlanan yanıtları yapılandırma kimlikleriyle anahtarlanmış bir nesne olarak veya kullanıcı herhangi bir yanıt sağlamazsa undefined olarak içerir.

Örnek:

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

Yapılandırmalar toplamsaldır

Yeni yapılandırma soruları, mevcut soruların ardından eklenmelidir.

Yapılandırmalar değiştirilemez

Daha önce bir yapılandırma sorusu sorulduysa bu soru, sonraki tüm görüşmelerde yer almalıdır. Örneğin, getConfig() için ilk çağrıda yapılandırma sorusu A sorulduysa A, gelecekteki tüm yanıtlara dahil edilmelidir.

Yapılandırmalar idempotent'tır

Aynı configParams ile yapılan getConfig() çağrıları aynı yapılandırmayı döndürmelidir.

Dinamik parametreler geçersiz kılınamaz

Data Studio, dinamik yapılandırma parametrelerinin geçersiz kılınmasına izin vermez.

Örnek yapılandırmalar

Dinamik açılır listeler

Bu ilk soruda kullanıcıdan bir eyalet seçmesi istenir. Ardından, seçilen eyalete göre dinamik olarak bir şehir açılır listesi sunulur.

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

Dallanan Yollar

Seçilen "Ülke" "ABD" ise ek bir soru sorulur.

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