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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сформируйте ответ на данные конференции.

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

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

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

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

При создании объекта 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;
}