Cấu hình theo từng bước

Cấu hình từng bước cho phép một trình kết nối tự động điền cấu hình trình kết nối dựa trên câu trả lời do người dùng cung cấp. Ví dụ: điền sẵn một trình đơn thả xuống "Thành phố" sau khi chọn một trình đơn thả xuống "Tiểu bang".

Yêu cầu

Hướng dẫn này giả định rằng bạn đã quen thuộc với các cấu hình Trình kết nối cộng đồng. Hãy xem phần xác định cấu hình thông qua getConfig để nắm lại kiến thức.

Tổng quan

Cấu hình từng bước bao gồm Data Studio gọi getConfig() nhiều lần và trình kết nối của bạn trả về nhiều câu hỏi về cấu hình hơn mỗi lần. Mỗi lệnh gọi đến getConfig() sẽ bao gồm câu trả lời của người dùng cho phản hồi getConfig() gần đây nhất. Quá trình này sẽ tiếp tục chừng nào bạn còn trả về một phản hồi bằng setIsSteppedConfig(true).

Nguyên tắc

Đặt setIsSteppedConfig(true) cho đến khi quá trình định cấu hình hoàn tất

Data Studio sẽ liên tục gọi getConfig() miễn là setIsSteppedConfig(true) được đặt.Sau khi hoàn tất cấu hình, phản hồi getConfig() cuối cùng sẽ đặt setIsSteppedConfig(false).

Đặt isDynamic(true) cho các câu hỏi định cấu hình để xác định các câu hỏi sau

Nếu người dùng sửa đổi một trường được đánh dấu isDynamic, thì các mục nhập cấu hình tiếp theo sẽ bị xoá trong giao diện người dùng và người dùng sẽ cần định cấu hình tất cả các bước tiếp theo. Điều này giúp đảm bảo người dùng không gửi cho bạn một cấu hình không hợp lệ.

Câu trả lời do người dùng cung cấp sẽ được truyền qua request.configParams.

request.configParams sẽ là undefined cho getConfig() yêu cầu đầu tiên đối với trình kết nối của bạn. Các yêu cầu tiếp theo sẽ bao gồm câu trả lời do người dùng cung cấp dưới dạng một đối tượng được khoá theo mã nhận dạng cấu hình hoặc undefined nếu người dùng không cung cấp câu trả lời nào.

Ví dụ:

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

Các cấu hình mang tính bổ sung

Bạn nên thêm các câu hỏi về cấu hình mới sau các câu hỏi hiện có.

Không thể thay đổi cấu hình

Nếu trước đó đã có câu hỏi về cấu hình, thì câu hỏi đó phải xuất hiện trong tất cả các lệnh gọi tiếp theo. Ví dụ: nếu câu hỏi về cấu hình A được hỏi trong lần gọi đầu tiên đến getConfig(), thì A phải được đưa vào tất cả các phản hồi trong tương lai.

Các cấu hình là bất biến

Các lệnh gọi đến getConfig() có cùng configParams sẽ trả về cùng một cấu hình.

Bạn không thể ghi đè các thông số động

Data Studio sẽ không cho phép ghi đè các thông số cấu hình động.

Cấu hình mẫu

Trình đơn thả xuống linh hoạt

Câu hỏi đầu tiên này nhắc người dùng chọn một tiểu bang, sau đó cung cấp một trình đơn thả xuống thành phố một cách linh hoạt dựa trên tiểu bang đã chọn.

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

Đường dẫn phân nhánh

Thao tác này sẽ đặt thêm một câu hỏi nếu "Quốc gia" bạn chọn là "Hoa Kỳ".

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