การกําหนดค่าแบบเป็นขั้น

การกำหนดค่าแบบเป็นขั้นตอนช่วยให้ตัวเชื่อมต่อสร้างการกำหนดค่าตัวเชื่อมต่อแบบไดนามิกตามคำตอบที่ผู้ใช้ระบุ เช่น การป้อนข้อมูลเมนูแบบเลื่อนลง "เมือง" หลังจากเลือกเมนูแบบเลื่อนลง "รัฐ"

ข้อกำหนด

คู่มือนี้ถือว่าคุณคุ้นเคยกับการกำหนดค่า Community Connector อยู่แล้ว โปรดดูกำหนดค่าผ่าน getConfig เพื่อทบทวน

ภาพรวม

การกำหนดค่าแบบเป็นขั้นตอนประกอบด้วย Data Studio ที่เรียกใช้getConfig()หลายครั้ง และตัวเชื่อมต่อจะแสดงคำถามการกำหนดค่าเพิ่มเติมในแต่ละครั้ง การเรียกใช้แต่ละครั้งไปยัง getConfig() จะรวมคำตอบของผู้ใช้สำหรับgetConfig() การตอบกลับครั้งล่าสุด กระบวนการนี้จะดำเนินต่อไปตราบเท่าที่คุณส่งคำตอบพร้อม setIsSteppedConfig(true)

หลักเกณฑ์

ตั้งค่า setIsSteppedConfig(true) จนกว่าการกำหนดค่าจะเสร็จสมบูรณ์

Data Studio จะเรียกใช้ getConfig() ซ้ำๆ ตราบใดที่ setIsSteppedConfig(true) ได้รับการตั้งค่า เมื่อการกำหนดค่าเสร็จสมบูรณ์แล้ว การตอบกลับ getConfig() สุดท้ายควรตั้งค่า setIsSteppedConfig(false)

ตั้งค่า isDynamic(true) สำหรับคำถามเกี่ยวกับการกำหนดค่าที่กำหนดคำถามในภายหลัง

หากผู้ใช้แก้ไขฟิลด์ที่ทำเครื่องหมาย isDynamic ไว้ ระบบจะล้างรายการการกำหนดค่าที่ตามมาใน UI และผู้ใช้จะต้องกำหนดค่าขั้นตอนต่อๆ ไปทั้งหมด ซึ่งจะช่วยให้มั่นใจได้ว่าผู้ใช้จะไม่ส่งการกำหนดค่าที่ไม่ถูกต้องให้คุณ

ระบบจะส่งคำตอบที่ผู้ใช้ระบุผ่าน request.configParams

request.configParams จะเป็น undefined สำหรับคำขอแรก getConfig() ที่ส่งไปยังตัวเชื่อมต่อ คำขอที่ตามมาจะมีคำตอบที่ผู้ใช้ระบุเป็นออบเจ็กต์ที่คีย์ด้วยรหัสการกำหนดค่าหรือ undefined หากผู้ใช้ไม่ได้ให้คำตอบใดๆ

ตัวอย่าง

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

การกำหนดค่าจะนับรายการเพิ่มจากที่มีอยู่

ควรเพิ่มคำถามการกำหนดค่าใหม่หลังจากคำถามที่มีอยู่

แก้ไขการกำหนดค่าไม่ได้

หากก่อนหน้านี้มีการถามคำถามเกี่ยวกับการกำหนดค่า คำถามนั้นควรปรากฏในการเรียกใช้ครั้งต่อๆ ไปทั้งหมด เช่น หากมีการถามคำถามการกำหนดค่า A ในการเรียกใช้ getConfig() ครั้งแรก คุณควรรวม A ไว้ในการตอบกลับในอนาคตทั้งหมด

การกำหนดค่าเป็นแบบ Idempotent

การเรียกใช้ 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();
}