สร้างการประชุมของบุคคลที่สาม

หมายเหตุ: ฟังก์ชันนี้สร้างขึ้นสำหรับผู้ให้บริการการประชุมโดยเฉพาะ และเดิมพร้อมให้บริการในรูปแบบส่วนเสริมการประชุมในปฏิทิน

โซลูชันการประชุมแต่ละรายการ ที่กำหนดไว้ในโปรเจ็กต์สคริปต์ ไฟล์ Manifest จะมี onCreateFunction ที่เชื่อมโยงกัน ส่วนเสริม Google Workspace จะเรียกใช้ฟังก์ชันนี้เพื่อสร้างการประชุมทุกครั้งที่ผู้ใช้พยายามเลือกโซลูชันการประชุมดังกล่าวสำหรับกิจกรรม

ใช้ onCreateFunction แต่ละรายการที่อธิบายไว้ใน ไฟล์ Manifest ของส่วนเสริม ฟังก์ชันเหล่านี้ต้องทำสิ่งต่อไปนี้

1. ดึงข้อมูลกิจกรรมใน Google ปฏิทิน เช่น รหัสกิจกรรมหรือ รายชื่อผู้เข้าร่วม ที่ระบบการประชุมของบุคคลที่สามต้องใช้เพื่อ สร้างการประชุม
2. เชื่อมต่อกับบริการการประชุมของบุคคลที่สามและสร้างการประชุมใหม่ โดยใช้ข้อมูลกิจกรรมในปฏิทิน
3. หากคำขอสร้างการประชุมล้มเหลว ให้ใช้ข้อมูลข้อผิดพลาดเพื่อสร้างและส่งคืนออบเจ็กต์ ConferenceData ที่มี ConferenceError หรือทำตามขั้นตอนถัดไป
4. เริ่มต้นการซิงค์การประชุม
5. ใช้ข้อมูลที่บริการการประชุมของบุคคลที่สามส่งกลับมาเพื่อสร้างและส่งกลับออบเจ็กต์ ConferenceData ใหม่

เรียกข้อมูลกิจกรรม

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

เมื่อเรียกใช้ ระบบจะส่งอาร์กิวเมนต์ที่มีรหัสปฏิทินและรหัสกิจกรรมไปยังแต่ละ onCreateFunction ที่คุณกำหนด ใช้รหัสเหล่านี้เพื่อดึงข้อมูลกิจกรรมแบบเต็ม โดยใช้ บริการขั้นสูงของปฏิทิน

ปฏิทินสามารถเพิ่มรายละเอียดการประชุมลงในกิจกรรมก่อนที่จะมีการประชุมได้ ในกรณีดังกล่าว ปฏิทินจะส่งonCreateFunctioneventIdที่ถูกต้อง แต่การเรียกใช้Calendar.Events.getในภายหลังอาจทำให้เกิดข้อผิดพลาดที่ระบุว่ากิจกรรมไม่มีอยู่ ในกรณีเหล่านี้ ให้สร้างการประชุมของบุคคลที่สามโดยใช้ข้อมูลตัวยึดตำแหน่ง ข้อมูลนี้จะถูกแทนที่ในครั้งถัดไปที่กิจกรรม ซิงค์

สร้างการประชุมของบุคคลที่สาม

หลังจากที่ onCreateFunction ดึงข้อมูลเหตุการณ์ที่จำเป็นแล้ว onCreateFunction จะต้องเชื่อมต่อกับระบบการประชุมของบุคคลที่สามเพื่อสร้างการประชุม โดยปกติแล้วจะทำได้ด้วยการส่งคำขอ API ที่ระบบการประชุมของบุคคลที่สามรองรับ โปรดอ่านเอกสารประกอบสำหรับโซลูชันการประชุมของบุคคลที่สามเพื่อดูคำขอ API ที่คุณใช้สร้างการประชุมได้

ใน Google Apps Script วิธีที่ง่ายที่สุดในการจัดการการส่งคำขอ API ภายนอก คือการใช้ OAuth2 สำหรับ Apps Script หรือ OAuth1 สำหรับ Apps Script ซึ่งเป็นไลบรารีโอเพนซอร์ส นอกจากนี้ คุณยังเชื่อมต่อกับ API ภายนอกโดยใช้บริการ UrlFetch ได้ด้วย แต่จะต้องจัดการรายละเอียดการให้สิทธิ์อย่างชัดเจน

หลังจากขอสร้างการประชุมแล้ว คุณอาจต้องส่งคำขอเพิ่มเติม เพื่อดึงรายละเอียดการประชุมใหม่

เริ่มต้นการซิงค์การประชุม

เมื่อส่วนเสริมสร้างการประชุมในระบบของบุคคลที่สามเรียบร้อยแล้ว คุณควรทำตาม 2-3 ขั้นตอนเพื่อเปิดใช้การซิงค์เพื่อให้การเปลี่ยนแปลงกิจกรรมในปฏิทินแสดงในการประชุม

ดูรายละเอียดเกี่ยวกับการตั้งค่าการซิงค์หลังจากสร้างการประชุมได้ที่ การซิงค์การเปลี่ยนแปลงในปฏิทิน

สร้างการตอบกลับข้อมูลการประชุม

โดยใช้ข้อมูลการประชุมที่บริการของบุคคลที่สามส่งกลับมา onCreateFunction จะต้องสร้างและส่งกลับออบเจ็กต์ ConferenceData จากนั้นส่วนข้อมูลการประชุม จะอธิบายเนื้อหาของออบเจ็กต์นี้ ปฏิทินใช้ข้อมูลนี้ เพื่อนำผู้ใช้ไปยังการประชุมเมื่อการประชุมเริ่มขึ้น

เมื่อสร้างออบเจ็กต์ ConferenceData โปรดทราบความยาวของฟิลด์ รูปแบบของ URI จุดแรกเข้า และชุดค่าผสมของจุดแรกเข้าที่อนุญาต เช่น ConferenceData รายการเดียวมีจุดแรกเข้าของ VIDEO ได้สูงสุด 1 จุด ข้อจำกัดเหล่านี้เหมือนกับ ข้อจำกัดที่อธิบายไว้ใน กิจกรรมใน Calendar API สำหรับ ฟิลด์ conferenceData ที่เกี่ยวข้อง แม้ว่าฟิลด์กิจกรรม API บางรายการที่อธิบายไว้ในนั้นจะไม่มีใน Apps Script

จัดการข้อผิดพลาด

ข้อผิดพลาดอาจเกิดขึ้นในระหว่างกระบวนการสร้างการประชุม ในบางกรณี การสร้างการประชุมอาจไม่สำเร็จเนื่องจากข้อผิดพลาดที่ระบบการประชุมของบุคคลที่สามส่งคืน ในกรณีเหล่านี้ ส่วนเสริมควรจัดการกับข้อผิดพลาดโดยการสร้าง และส่งคืนออบเจ็กต์ ConferenceData ที่มีรายละเอียด ConferenceError เพื่อให้ปฏิทินดำเนินการตามนั้นได้

เมื่อสร้างออบเจ็กต์ ConferenceData เพื่อรายงานข้อผิดพลาด คุณไม่จำเป็นต้อง รวมคอมโพเนนต์ ConferenceData ใดๆ นอกเหนือจากออบเจ็กต์ ConferenceError ConferenceErrors อาจมี ConferenceErrorType ข้อความแสดงข้อผิดพลาด และสำหรับปัญหาการตรวจสอบสิทธิ์ URL ที่อนุญาตให้ผู้ใช้เข้าสู่ระบบ ระบบการประชุมของบุคคลที่สาม

ส่วนเสริมของคุณ ไม่จำเป็นต้องพยายามตั้งค่าการซิงค์การประชุมหากความพยายาม ในการสร้างการประชุมล้มเหลว

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้งาน onCreateFunction ชื่อฟังก์ชันจะเป็นอะไรก็ได้ คุณเพียงแค่ต้องกำหนดชื่อในไฟล์ Manifest ของโปรเจ็กต์ส่วนเสริม

ฟังก์ชัน create3rdPartyConference จะติดต่อระบบของบุคคลที่สามเพื่อ สร้างการประชุม และฟังก์ชัน getAuthenticationUrl จะสร้าง URL การตรวจสอบสิทธิ์ของระบบของบุคคลที่สาม ฟีเจอร์เหล่านี้ยังไม่พร้อมใช้งานที่นี่

ฟังก์ชัน initializeSyncing ไม่ได้แสดงที่นี่ แต่จะจัดการงานเบื้องต้น ที่จำเป็นสำหรับการซิงค์ ดูรายละเอียดได้ที่ ซิงค์การเปลี่ยนแปลงในปฏิทิน

/**
 *  Creates a conference, then builds and returns a ConferenceData object
 *  with the corresponding conference information. This method is called
 *  when a user selects a conference solution defined by the add-on that
 *  uses this function as its 'onCreateFunction' in the add-on manifest.
 *
 *  @param {Object} arg The default argument passed to a 'onCreateFunction';
 *      it carries information about the Google Calendar event.
 *  @return {ConferenceData}
 */
function createConference(arg) {
  const eventData = arg.eventData;
  const calendarId = eventData.calendarId;
  const eventId = eventData.eventId;

  // Retrieve the Calendar event information using the Calendar
  // Advanced service.
  var calendarEvent;
  try {
    calendarEvent = Calendar.Events.get(calendarId, eventId);
  } catch (err) {
    // The calendar event does not exist just yet; just proceed with the
    // given event ID and allow the event details to sync later.
    console.log(err);
    calendarEvent = {
      id: eventId,
    };
  }

  // Create a conference on the third-party service and return the
  // conference data or errors in a custom JSON object.
  var conferenceInfo = create3rdPartyConference(calendarEvent);

  // Build and return a ConferenceData object, either with conference or
  // error information.
  var dataBuilder = ConferenceDataService.newConferenceDataBuilder();

  if (!conferenceInfo.error) {
    // No error, so build the ConferenceData object from the
    // returned conference info.

    var phoneEntryPoint = ConferenceDataService.newEntryPoint()
        .setEntryPointType(ConferenceDataService.EntryPointType.PHONE)
        .setUri('tel:+' + conferenceInfo.phoneNumber)
        .setPin(conferenceInfo.phonePin);

    var adminEmailParameter = ConferenceDataService.newConferenceParameter()
        .setKey('adminEmail')
        .setValue(conferenceInfo.adminEmail);

    dataBuilder.setConferenceId(conferenceInfo.id)
        .addEntryPoint(phoneEntryPoint)
        .addConferenceParameter(adminEmailParameter)
        .setNotes(conferenceInfo.conferenceLegalNotice);

    if (conferenceInfo.videoUri) {
      var videoEntryPoint = ConferenceDataService.newEntryPoint()
          .setEntryPointType(ConferenceDataService.EntryPointType.VIDEO)
          .setUri(conferenceInfo.videoUri)
          .setPasscode(conferenceInfo.videoPasscode);
      dataBuilder.addEntryPoint(videoEntryPoint);
    }

    // Since the conference creation request succeeded, make sure that
    // syncing has been enabled.
    initializeSyncing(calendarId, eventId, conferenceInfo.id);

  } else if (conferenceInfo.error === 'AUTH') {
    // Authenentication error. Implement a function to build the correct
    // authenication URL for the third-party conferencing system.
    var authenticationUrl = getAuthenticationUrl();
    var error = ConferenceDataService.newConferenceError()
        .setConferenceErrorType(
            ConferenceDataService.ConferenceErrorType.AUTHENTICATION)
        .setAuthenticationUrl(authenticationUrl);
    dataBuilder.setError(error);

  } else {
    // Other error type;
    var error = ConferenceDataService.newConferenceError()
        .setConferenceErrorType(
            ConferenceDataService.ConferenceErrorType.TEMPORARY);
    dataBuilder.setError(error);
  }

  // Don't forget to build the ConferenceData object.
  return dataBuilder.build();
}


/**
 *  Contact the third-party conferencing system to create a conference there,
 *  using the provided calendar event information. Collects and retuns the
 *  conference data returned by the third-party system in a custom JSON object
 *  with the following fields:
 *
 *    data.adminEmail - the conference administrator's email
 *    data.conferenceLegalNotice - the conference legal notice text
 *    data.error - Only present if there was an error during
 *         conference creation. Equal to 'AUTH' if the add-on user needs to
 *         authorize on the third-party system.
 *    data.id - the conference ID
 *    data.phoneNumber - the conference phone entry point phone number
 *    data.phonePin - the conference phone entry point PIN
 *    data.videoPasscode - the conference video entry point passcode
 *    data.videoUri - the conference video entry point URI
 *
 *  The above fields are specific to this example; which conference information
 *  your add-on needs is dependent on the third-party conferencing system
 *  requirements.
 *
 * @param {Object} calendarEvent A Calendar Event resource object returned by
 *     the Google Calendar API.
 * @return {Object}
 */
function create3rdPartyConference(calendarEvent) {
  var data = {};

  // Implementation details dependent on the third-party system API.
  // Typically one or more API calls are made to create the conference and
  // acquire its relevant data, which is then put in to the returned JSON
  // object.

  return data;
}

/**
 *  Return the URL used to authenticate the user with the third-party
 *  conferencing system.
 *
 *  @return {String}
 */
function getAuthenticationUrl() {
  var url;
  // Implementation details dependent on the third-party system.

  return url;
}