Konfigurasi Berlangkah

Konfigurasi bertahap memungkinkan konektor mengisi konfigurasi konektor secara dinamis berdasarkan jawaban yang diberikan pengguna. Misalnya, mengisi dropdown "Kota" setelah dropdown "Negara Bagian" dipilih.

Persyaratan

Panduan ini mengasumsikan bahwa Anda sudah memahami konfigurasi Konektor Komunitas. Lihat menentukan konfigurasi melalui getConfig untuk mengingat kembali.

Ringkasan

Konfigurasi bertahap terdiri dari Data Studio yang memanggil getConfig() beberapa kali, dan konektor Anda menampilkan lebih banyak pertanyaan konfigurasi setiap kali. Setiap panggilan ke getConfig() akan menyertakan jawaban pengguna untuk respons getConfig() terakhir. Proses ini akan dilanjutkan selama Anda menampilkan respons dengan setIsSteppedConfig(true).

Panduan

Tetapkan setIsSteppedConfig(true) hingga konfigurasi selesai

Data Studio akan berulang kali memanggil getConfig() selama setIsSteppedConfig(true) ditetapkan.Setelah konfigurasi selesai, respons getConfig() akhir harus menetapkan setIsSteppedConfig(false).

Tetapkan isDynamic(true) untuk pertanyaan konfigurasi yang menentukan pertanyaan berikutnya

Jika kolom yang ditandai isDynamic diubah oleh pengguna, entri konfigurasi berikutnya akan dihapus di UI, dan pengguna harus mengonfigurasi semua langkah berikutnya. Hal ini membantu memastikan pengguna tidak mengirimkan konfigurasi yang tidak valid kepada Anda.

Jawaban yang diberikan pengguna akan diteruskan melalui request.configParams.

request.configParams akan menjadi undefined untuk permintaan getConfig() pertama ke konektor Anda. Permintaan berikutnya akan menyertakan jawaban yang diberikan pengguna sebagai objek yang dikunci oleh ID konfigurasi atau undefined jika pengguna tidak memberikan jawaban apa pun.

Contoh:

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

Konfigurasi bersifat menambah

Pertanyaan konfigurasi baru harus ditambahkan setelah pertanyaan yang ada.

Konfigurasi tidak dapat diubah

Jika pertanyaan konfigurasi telah diajukan sebelumnya, pertanyaan tersebut harus ada untuk semua panggilan berikutnya. Misalnya, jika pertanyaan konfigurasi A diajukan pada panggilan pertama ke getConfig(), A harus disertakan dalam semua respons mendatang.

Konfigurasi bersifat idempoten

Panggilan ke getConfig() dengan configParams yang sama harus menampilkan konfigurasi yang sama.

Parameter dinamis tidak dapat diganti

Data Studio tidak akan mengizinkan parameter konfigurasi dinamis di ganti.

Contoh konfigurasi

Dropdown dinamis

Pertanyaan pertama ini meminta pengguna untuk memilih negara bagian, lalu menyediakan dropdown kota secara dinamis berdasarkan negara bagian yang dipilih.

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

Jalur Percabangan

Pertanyaan tambahan akan diajukan jika "Negara" yang dipilih adalah "Amerika Serikat".

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