Cada solução de conferência
definida no manifesto
do projeto de script
tem uma onCreateFunction
associada. O complemento chama essa função para criar
uma conferência sempre que um usuário tenta selecionar essa solução de
conferência em um evento.
Implemente cada onCreateFunction
descrito no manifesto do complemento.
Em geral, essas funções precisam fazer o seguinte:
- Recuperar todas as informações de eventos do Google Agenda, como o ID do evento ou a lista de convidados, que o sistema de videoconferência de terceiros possa precisar para criar a videoconferência.
- Conecte-se ao serviço de videoconferência de terceiros e crie uma nova conferência usando as informações do evento do Google Agenda.
- Se a solicitação de criação de conferência falhar por algum motivo, use as informações de erro
para criar e retornar um objeto
ConferenceData
que contenha umConferenceError
. Caso contrário, siga as próximas etapas.- Inicialize a sincronização da conferência.
- Use as informações retornadas pelo serviço de videoconferência de terceiros para
criar e retornar um novo objeto
ConferenceData
.
Como recuperar informações de eventos
Para criar uma videoconferência de terceiros, é necessário ter algumas informações sobre o evento correspondente do Google Agenda. As informações exatas do evento necessárias variam entre os diferentes sistemas de conferência de terceiros, mas geralmente isso inclui os horários de início e término, resumo, lista de participantes e identificação do evento.
Quando chamado, cada onCreateFunction
que você define recebe um argumento que
contém os IDs da agenda e do evento. Use esses IDs para recuperar todas as informações do evento usando o serviço avançado do Google Agenda.
O Google Agenda pode adicionar detalhes da videoconferência a um evento antes que ele exista. Nesses casos, o Google Agenda transmite a onCreateFunction
um eventId
válido, mas chamadas subsequentes para Calendar.Events.get()
podem resultar em uma
resposta de erro informando que o evento não existe. Nesses casos, é melhor
criar a conferência de terceiros usando dados de marcador de posição. Esses dados são substituídos
na próxima vez que o evento for
sincronizado.
Como criar a conferência de terceiros
Depois que a onCreateFunction
recuperar os dados de evento necessários, ela precisará
se conectar ao sistema de conferências de terceiros para criar a conferência.
Normalmente, isso é conseguido fazendo solicitações de API compatíveis com o sistema de conferência de terceiros. Consulte a documentação da solução de conferências
de terceiros para determinar quais solicitações de API você pode usar para criar
conferências.
No Apps Script, a maneira mais fácil de processar solicitações de API externas é usando as bibliotecas de código aberto OAuth2 para Apps Script ou OAuth1 para Apps Script. Também é possível se conectar a APIs externas usando o serviço UrlFetch, mas isso exige que você processe os detalhes da autorização explicitamente.
Depois de solicitar a criação da videoconferência, pode ser necessário fazer outras solicitações para recuperar os novos detalhes da videoconferência.
Inicializar a sincronização de videoconferência
Depois que o complemento criar uma conferência em um sistema de terceiros, será necessário seguir algumas etapas para ativar a sincronização para que as mudanças no evento do Google Agenda sejam refletidas na conferência.
Consulte Como sincronizar mudanças na Agenda para saber como configurar a sincronização após a criação da conferência.
Como criar uma resposta de dados de conferência
Usando as informações da conferência retornadas pelo serviço de terceiros,
o onCreateFunction
precisa criar e retornar um objeto
ConferenceData
.
A seção
Dados da conferência
descreve o conteúdo desse objeto. O Google Agenda usa essas informações para direcionar os usuários à reunião quando ela é iniciada.
Ao criar um objeto ConferenceData
,
é importante saber que há algumas limitações nos comprimentos de campo, nos formatos de
URIs de ponto de entrada e nas combinações permitidas de pontos de entrada. Por exemplo,
pode haver no máximo um ponto de entrada VIDEO
em um único
ConferenceData
. Essas limitações são idênticas às descritas na seção Evento da API Calendar para o campo conferenceData
correspondente, embora nem todos os campos de evento da API descritos estejam disponíveis no Apps Script.
Como processar os erros
Em alguns casos, a criação da conferência não pode ser concluída devido
a um erro retornado pelo sistema de conferências de terceiros. Nesses casos,
seu complemento precisa lidar com a condição de erro de forma robusta, criando e
retornando um objeto
ConferenceData
com detalhes
ConferenceError
,
para que o Google Agenda possa agir de acordo.
Ao criar um objeto ConferenceData
para informar um erro, não
é necessário incluir componentes ConferenceData
além do
objeto ConferenceError
. O ConferenceErrors
pode ter um
ConferenceErrorType
,
uma mensagem de erro e, no caso de autenticação, emite um URL que permite
que os usuários façam login no sistema de videoconferência de terceiros.
Exemplo
O exemplo a seguir mostra um onCreateFunction
. O nome da
função pode ser qualquer coisa. Basta defini-lo no manifesto do projeto
de complemento.
A função create3rdPartyConference()
entra em contato com o sistema de terceiros para criar a conferência, e a função getAuthenticationUrl()
cria um URL de autenticação do sistema de terceiros. Elas não estão implementadas
completamente aqui, porque dependem muito dos detalhes do sistema de terceiros.
A função initializeSyncing()
não é mostrada aqui. Ela processa qualquer trabalho preliminar
necessário para a sincronização.
Consulte Sincronizar mudanças na agenda
para mais detalhes.
/** * 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; }