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

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

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

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

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

กำลังดึงข้อมูลกิจกรรม

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

เมื่อสร้างออบเจ็กต์ 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;
}