Criação de conferências de terceiros

Cada solução de conferência definida no manifesto do projeto de script tem um onCreateFunction associado. O complemento chama essa função para criar uma videoconferência sempre que um usuário tenta selecionar essa solução de videoconferência como um evento.

Implemente cada onCreateFunction descrito no manifesto do complemento. Em geral, essas funções precisam fazer o seguinte:

1. Recupere todas as informações de eventos do Google Agenda, como o ID do evento ou a lista de participantes, que o sistema de videoconferência de terceiros pode precisar para criar a videoconferência.
2. conectar-se ao serviço de videoconferência de terceiros e criar uma nova videoconferência usando as informações do evento do Google Agenda;
3. Se a solicitação de criação de videoconferência falhar por algum motivo, use as informações do erro para criar e retornar um objeto ConferenceData contendo um ConferenceError. Caso contrário, conclua as próximas etapas.
   1. Inicializar a sincronização de videoconferências.
   2. 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 conferência de terceiros, é necessário ter determinadas informações sobre o evento correspondente do Google Agenda. As informações exatas do evento necessárias variam de acordo com os diferentes sistemas de conferência de terceiros, mas geralmente isso inclui o horário de início e de término, o resumo, a lista de participantes e o ID.

Quando chamada, cada onCreateFunction definido recebe um argumento que contém os IDs de eventos e agendas. Você pode usar esses IDs para recuperar as informações completas do evento usando o serviço avançado do Google Agenda.

O Google Agenda pode adicionar detalhes de videoconferência a um evento antes de ele existir. Nesses casos, o Google Agenda transmite ao onCreateFunction um eventId válido, mas as 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 marcadores, que serão substituídos na próxima vez que o evento sincronizar.

Como criar a videoconferência de terceiros

Depois que o onCreateFunction recupera os dados necessários do evento, ele precisa se conectar ao sistema de videoconferência de terceiros para criar a videoconferência. Normalmente, isso é feito por meio de solicitações de API compatíveis com o sistema de videoconferência de terceiros. Verifique a documentação da solução de videoconferência de terceiros para determinar quais solicitações de API podem ser usadas para criar conferências.

No Apps Script, a maneira mais fácil de lidar com solicitações de API externas é usar as bibliotecas de código aberto OAuth2 para Apps Script ou OAuth1 para Apps Script. Você também pode conectar-se a APIs externas usando o serviço UrlFetch, mas isso exige que você lide com os detalhes de autorização explicitamente.

Depois de solicitar a criação da videoconferência, talvez seja necessário fazer outras solicitações para recuperar os novos detalhes da videoconferência.

Inicializar a sincronização de videoconferências

Depois que o complemento criar uma videoconferência em um sistema de terceiros, será necessário ativar a sincronização para que as alterações no evento do Google Agenda sejam refletidas na videoconferência.

Consulte Sincronizar alterações no Google Agenda para detalhes sobre como configurar a sincronização após a criação da videoconferência.

Como criar uma resposta de dados de videoconferência

Usando as informações de videoconferência retornadas pelo serviço de terceiros, o onCreateFunction precisa criar e retornar um objeto ConferenceData. A seção Dados da videoconferência descreve o conteúdo desse objeto. O Google Agenda utiliza essas informações para direcionar os usuários para a videoconferência quando ela for iniciada.

Ao criar um objeto ConferenceData, esteja ciente de que existem algumas limitações quanto a comprimentos de campo, formatos de URIs de ponto de entrada e as 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 em Evento da API Calendar para o campo conferenceData correspondente, embora nem todos os campos de eventos de API descritos estão disponíveis no Apps Script.

Como processar os erros

Em alguns casos, não é possível concluir a criação da videoconferência devido a um erro retornado pelo sistema de videoconferência de terceiros. Nesses casos, seu complemento precisa processar a condição de erro de forma eficiente criando e retornando um objeto ConferenceData contendo detalhes de ConferenceError para que o Google Agenda possa agir corretamente.

Ao criar um objeto ConferenceData para informar um erro, não é necessário incluir componentes ConferenceData além do objeto ConferenceError. ConferenceErrors pode ter uma ConferenceErrorType, uma mensagem de erro e, no caso de problemas de autenticação, um URL que permite que os usuários façam login no sistema de videoconferência de terceiros.

Observação :seu complemento não vai precisar tentar configurar a sincronização de videoconferência se a tentativa de criação de videoconferência falhar.

Exemplo

Confira abaixo um exemplo de onCreateFunction. O nome da função pode ser qualquer coisa, você só precisa defini-la no manifesto do projeto do complemento.

A função create3rdPartyConference() entra em contato com o sistema de terceiros para criar a videoconferência no local, e a função getAuthenticationUrl() cria um URL de autenticação do sistema de terceiros. Eles não são implementados totalmente aqui, porque dependem 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 alterações 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;
}