Эта страница переведена с помощью Cloud Translation API.

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

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

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

Получите любую информацию о событии Календаря Google, например идентификатор события или список участников, которая может потребоваться сторонней системе конференц-связи для создания конференции.
Подключитесь к сторонней службе конференц-связи и создайте там новую конференцию, используя информацию о событиях Календаря Google.
Если по какой-либо причине запрос на создание конференции не удалось выполнить, используйте информацию об ошибке для создания и возврата объекта 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;
}