Создание сторонних конференций

Каждое решение конференции , определенное вами в манифесте проекта скрипта, имеет связанную onCreateFunction . Надстройка вызывает эту функцию для создания конференции всякий раз, когда пользователь пытается выбрать это решение конференции в качестве события.

Вы должны реализовать каждую onCreateFunction описанную в манифесте вашей надстройки. В целом эти функции должны выполнять следующее:

  1. Получите любую информацию о событии Календаря Google, например идентификатор события или список участников, которая может потребоваться сторонней системе конференц-связи для создания конференции.
  2. Подключитесь к стороннему сервису конференц-связи и создайте там новую конференцию, используя информацию о событиях Календаря Google.
  3. Если по какой-либо причине запрос на создание конференции не удалось выполнить, используйте информацию об ошибке для создания и возврата объекта ConferenceData , содержащего ConferenceError . В противном случае выполните следующие шаги.
    1. Инициализируйте синхронизацию конференций.
    2. Используйте информацию, возвращаемую сторонней службой конференц-связи, для создания и возврата нового объекта ConferenceData .

Получение информации о событии

Для создания сторонней конференции необходима определенная информация о соответствующем событии Календаря Google. Точная необходимая информация о событии различается в зависимости от сторонних конференц-систем, но часто она включает время начала и окончания мероприятия, сводку, список участников и идентификатор.

При вызове каждой определяемой вами onCreateFunction передается аргумент, содержащий идентификаторы календаря и событий. Вы можете использовать эти идентификаторы для получения полной информации о мероприятии с помощью расширенной службы Календаря Google .

Календарь Google может добавить сведения о конференции к событию до его существования. В таких случаях Календарь Google передает onCreateFunction действительный eventId , но последующие вызовы Calendar.Events.get() могут привести к ответу об ошибке, сообщающему, что событие не существует. В таких случаях лучше всего создать стороннюю конференцию, используя данные-заполнители; эти данные заменяются при следующей синхронизации события.

Создание сторонней конференции

После того как функция onCreateFunction получит необходимые данные о событии, она должна подключиться к сторонней системе конференц-связи для создания конференции. Обычно это достигается путем отправки запросов API, поддерживаемых сторонней системой конференц-связи. Ознакомьтесь с документацией стороннего решения для конференц-связи, чтобы определить, какие запросы API можно использовать для создания конференций.

В Apps Script самый простой способ обработки внешних запросов API — использование библиотек с открытым исходным кодом OAuth2 для Apps Script или OAuth1 для Apps Script . Вы также можете подключиться к внешним API с помощью службы UrlFetch , но для этого вам потребуется явно обрабатывать данные авторизации.

После запроса на создание конференции вам может потребоваться сделать дополнительные запросы для получения сведений о новой конференции.

Инициализация синхронизации конференций

После того как надстройка успешно создаст конференцию в сторонней системе, ей необходимо выполнить несколько шагов, чтобы включить синхронизацию , чтобы изменения в событии Календаря Google были отражены в конференции.

Подробную информацию о настройке синхронизации после создания конференции см. в разделе Синхронизация изменений календаря .

Создание ответа на данные конференции

Используя информацию о конференции, возвращаемую сторонней службой, onCreateFunction должна затем создать и вернуть объект ConferenceData ; раздел данных конференции описывает содержимое этого объекта. Календарь Google использует эту информацию, чтобы направлять пользователей на конференцию после ее начала.

При создании объекта ConferenceData имейте в виду, что существуют некоторые ограничения на длину полей, форматы URI точек входа и разрешенные комбинации точек входа. Например, в одном ConferenceData может быть не более одной точки входа VIDEO . Эти ограничения идентичны ограничениям, описанным в событии API календаря для соответствующего поля conferenceData , хотя не все описанные там поля событий API доступны в Apps Script.

Обработка ошибок

В некоторых случаях создание конференции не может быть завершено из-за ошибки, возвращаемой сторонней системой конференц-связи. В этих случаях ваша надстройка должна надежно обрабатывать ситуацию ошибки, создавая и возвращая объект ConferenceData , содержащий сведения об ошибке ConferenceError , чтобы Календарь Google мог действовать соответствующим образом.

При создании объекта ConferenceData для сообщения об ошибке вам не нужно включать какие-либо компоненты ConferenceData , кроме объекта ConferenceError . ConferenceErrors может иметь ConferenceErrorType — сообщение об ошибке, а в случае аутентификации — URL-адрес, позволяющий пользователям войти в стороннюю систему конференц-связи.

Пример

Ниже показан пример onCreateFunction (обратите внимание, что имя функции может быть любым; вам нужно только определить его в манифесте проекта надстройки).

Функция 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;
}