發起第三方會議

您在指令碼專案資訊清單中定義的每個會議解決方案都有相關聯的 onCreateFunction，外掛程式會在使用者嘗試選取某場會議解決方案時，呼叫此函式以建立會議。

您必須實作外掛程式資訊清單中描述的所有 onCreateFunction。一般來說，這些函式必須執行以下動作：

1. 擷取任何 Google 日曆活動資訊，例如活動 ID 或參與者名單，以便第三方會議系統建立會議。
2. 連線至第三方會議服務，並使用 Google 日曆活動在該處建立新會議。
3. 如果會議建立要求因故失敗，請使用錯誤資訊建構並傳回包含 ConferenceError 的 ConferenceData 物件。 否則，請完成後續步驟。
   1. 初始化會議同步。
   2. 使用第三方會議通訊服務傳回的資訊，建構並傳回新的 ConferenceData 物件。

擷取活動資訊

需要建立第三方會議，以便使用對應 Google 日曆活動的特定資訊。不同第三方會議系統需要的確切活動資訊各不相同，但通常包含活動開始時間、結束時間、摘要、參與者清單和 ID。

呼叫呼叫時，您定義的每個 onCreateFunction 都會傳遞包含日曆和活動 ID 的引數。您可以使用這些 ID，在 Google 日曆進階服務中擷取完整的活動資訊。

Google 日曆可以事先在活動中新增會議詳細資料。在這種情況下，Google 日曆會傳遞 onCreateFunction 有效的 eventId有效回應，但對 Calendar.Events.get() 的後續呼叫可能會導致錯誤回應，指出活動不存在。在這類情況下，最好使用預留位置資料建立第三方會議；系統會在下次事件同步處理時取代這項資料。

建立第三方會議

onCreateFunction 擷取必要的事件資料後，必須連線至第三方會議系統才能建立會議。一般來說，您需要發出第三方會議系統支援的 API 要求來完成這項工作。請參閱第三方會議解決方案的說明文件，以判斷哪些 API 要求可用於建立會議。

在 Apps Script 中，處理外部 API 要求最簡單的方式，就是使用 Apps Script 的 OAuth2 或 Apps Script 的 OAuth1 開放原始碼程式庫。您也可以使用 UrlFetch 服務連線至外部 API，但這需要明確處理授權詳細資料。

要求建立會議後，您可能需要提出其他要求，才能擷取新的會議詳細資料。

初始化會議同步處理

外掛程式在第三方系統上成功建立會議後，應該會執行同步處理程序，使 Google 日曆活動的變更反映在會議中。

如要進一步瞭解如何在建立會議後設定同步處理，請參閱「同步處理日曆變更」。

建立會議資料回應

使用第三方服務傳回的會議資訊時，onCreateFunction 必須建構並傳回 ConferenceData 物件；「會議資料」一節將說明這個物件的內容。Google 日曆會使用這項資訊，在會議開始後將使用者導向至會議。

建構 ConferenceData 物件時，請注意欄位長度、進入點 URI 格式和允許的進入點組合會有一些限制。舉例來說，單一 ConferenceData 最多只能有一個 VIDEO 進入點。這些限制與 Calendar API 事件中對應 conferenceData 欄位所說明的限制相同，不過，Apps Script 中並未提供所有的 API 事件欄位。

處理錯誤

在某些情況下，由於第三方會議系統傳回錯誤，因此無法完成會議建立作業。在這些情況下，外掛程式應建構並傳回包含 ConferenceError 詳細資料的 ConferenceData 物件，以便妥善處理錯誤狀況，以便 Google 日曆據此採取行動。

建構 ConferenceData 物件來回報錯誤時，除了 ConferenceError 物件之外，您不需要加入任何 ConferenceData 元件。ConferenceErrors 可以包含 ConferenceErrorType、錯誤訊息；在驗證發生問題時，可以使用可讓使用者登入第三方會議系統的網址。

注意： 如果會議建立失敗，外掛程式就不需要嘗試設定會議同步處理作業。

範例

以下為 onCreateFunction 範例 (請注意，函式名稱可以是任何內容，只需要在外掛程式專案資訊清單中定義)。

create3rdPartyConference() 函式會聯絡第三方系統建立會議，getAuthenticationUrl() 函式則會建立第三方系統驗證網址。由於這些實作方式高度仰賴第三方系統的詳細資料，因此此處並未完整實作。

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