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