创建第三方会议

每个会议解决方案 您在脚本项目中定义的 清单 具有关联的 onCreateFunction。该插件会调用此函数 每当用户尝试选择该会议解决方案 事件。

您必须实现插件清单中所述的每个 onCreateFunction。 通常,这些函数必须执行以下操作:

  1. 检索任何 Google 日历活动信息,例如活动 ID 或 参加者列表,而第三方会议系统可能需要 以便创建会议
  2. 连接到第三方会议服务并创建新会议 (使用 Google 日历活动信息)。
  3. 如果会议创建请求由于某种原因失败,请使用错误消息 生成并返回一个 ConferenceData 包含 ConferenceError。 否则,请完成后续步骤。
    1. 初始化会议同步功能。
    2. 将第三方会议服务返回的信息用于 构建并返回一个新的 ConferenceData 对象。

检索活动信息

要创建第三方会议,请了解关于相应会议 需要设置 Google 日历活动。所需的确切事件信息因情况而异 不同第三方会议系统之间的工作,但通常包括 活动开始时间、结束时间、摘要、参加者列表和 ID。

调用时,您定义的每个 onCreateFunction 都会传递一个实参, 包含日历和活动 ID。您可以使用这些 ID 检索 使用 Google 日历高级服务

Google 日历可以在活动之前 存在。在这种情况下,Google 日历会向 onCreateFunction 传递有效的 eventId,但对 Calendar.Events.get() 的后续调用可能会导致 表示事件不存在的错误响应。在这些情况下,最好 使用占位数据创建第三方会议;这些数据被替换 下一次活动时 同步

创建第三方会议

onCreateFunction 检索到必要的事件数据后,必须 连接到第三方会议系统以创建会议。 这通常通过发出受 API 支持的 API 请求来实现, 第三方会议系统查看第三方的相关文档 会议解决方案,以确定您可以使用哪些 API 请求来创建 会议。

在 Apps 脚本中,处理发出外部 API 请求的最简单方法是 使用适用于 Apps 脚本的 OAuth2适用于 Apps 脚本的 OAuth1 开源库。您还可以 使用 UrlFetch 服务连接到外部 API, 但这需要您明确处理授权详情。

请求创建会议后,您可能需要为会议 检索新会议详细信息的请求。

初始化会议同步功能

当该插件在第三方系统上成功创建会议后, 需要执行几个步骤来启用 syncing 更改为 Google 日历活动会反映在会议中。

请参阅同步日历更改 了解有关在创建会议后设置同步的详情。

构建会议数据响应

根据第三方服务返回的会议信息 然后,onCreateFunction 必须构建并返回 ConferenceData object; 会议数据 部分介绍了此对象的内容。Google 日历会使用 使用该信息在会议开始后引导用户加入该会议。

构建 ConferenceData 时 对象时,请注意字段长度、 入口点 URI 以及允许的入口点组合。例如: 单个中最多只能有一个 VIDEO 入口点 ConferenceData。这些限制与上述限制 日历 API 事件中相应的 conferenceData 字段,但此处描述的并非全部 API 事件字段 支持在 Apps 脚本中使用。

处理错误

在某些情况下,会议创建无法完成,这是因为 或第三方会议系统返回的错误在这些情况下 您的插件应该通过构建并 返回 ConferenceData 对象包含 ConferenceError 以便 Google 日历相应地采取行动。

构造 ConferenceData 对象以报告错误时,您不需要 除了ConferenceData ConferenceError 对象。ConferenceErrorsConferenceErrorType, 错误消息,如果身份验证发出,则会提供一个网址, 用户可以登录第三方会议系统。

示例

下面显示了 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;
}