Esta página foi traduzida pela API Cloud Translation.

Criação de conferências de terceiros

cada solução de conferência que você definiu em seu projeto de script manifestar tem um onCreateFunction associado. O complemento chama essa função para criar uma videoconferência sempre que um usuário tentar selecionar essa solução de conferência evento.

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

Recuperar informações de eventos do Google Agenda, como ID ou lista de participantes, de que o sistema de videoconferência de terceiros pode precisar para criar a conferência.
Conecte-se ao serviço de videoconferência de terceiros e crie uma nova videoconferência usando as informações de eventos do Google Agenda.
Se a solicitação de criação de conferência tiver falhado por algum motivo, use o erro informações para criar e retornar ConferenceData que contém um objeto ConferenceError Caso contrário, conclua as próximas etapas.
1. Inicialize a sincronização de videoconferências.
2. Usar as informações retornadas pelo serviço de videoconferência de terceiros para criar e retornar ConferenceData objeto.

Como recuperar informações de eventos

Para criar uma conferência de terceiros, forneça determinadas informações sobre o evento É necessário um evento do Google Agenda. As informações exatas do evento necessárias variam entre diferentes sistemas de conferência de terceiros, mas muitas vezes isso inclui os horário de início e de término do evento, resumo, lista de participantes e ID.

Quando chamado, cada onCreateFunction que você define recebe um argumento que contém as IDs da agenda e do evento. Você pode usar esses IDs para recuperar os informações completas do evento usando o serviço avançado do Google Agenda.

O Google Agenda pode adicionar detalhes da videoconferência a um evento antes de ele existe. Nesses casos, o Google Agenda transmite ao onCreateFunction uma mensagem eventId, 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 espaço reservado; esses dados são substituídos na próxima vez que o evento sincroniza.

Como criar a conferência de terceiros

Depois que o onCreateFunction recupera os dados necessários do evento, ele precisa conectar ao sistema de videoconferência de terceiros para criar a videoconferência. Normalmente, isso é conseguido fazendo solicitações de API suportadas pelo sistema de videoconferência de terceiros. Consulte a documentação do serviço de terceiros de videoconferência para determinar quais solicitações de API podem ser usadas para criar conferências.

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

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

Inicializar a sincronização de videoconferência

Assim que o complemento criar uma videoconferência em um sistema de terceiros, será necessário seguir algumas etapas para ativar syncing para que mude evento do Google Agenda são refletidas na conferência.

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

Como criar uma resposta de dados de conferência

Com as informações de conferência retornadas pelo serviço de terceiros, o onCreateFunction precisa criar e retornar um ConferenceData objeto; as Dados da videoconferência descreve o conteúdo desse objeto. O Google Agenda usa este usa essas informações para direcionar os usuários para a conferência assim que ela for iniciada.

Ao criar um ConferenceData objeto, esteja ciente de que existem algumas limitações em 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 no Evento da API Calendar para o evento conferenceData, mas nem todos os campos de evento da API descritos disponíveis no Apps Script.

Como processar os erros

Em alguns casos, não é possível concluir a criação da conferência porque de um erro retornado pelo sistema de videoconferência de terceiros. Nesses casos, seu complemento deve lidar de forma robusta com a condição de erro criando e retornando um ConferenceData que contém ConferenceError detalhes, para que o Google Agenda possa agir de acordo.

Ao criar um objeto ConferenceData para informar um erro, não é necessário é necessário incluir componentes ConferenceData além dos objeto ConferenceError. ConferenceErrors pode ter um ConferenceErrorType, uma mensagem de erro e, no caso da autenticação, emite um URL que permite fazer login no sistema de videoconferência de terceiros.

Exemplo

Confira abaixo um exemplo de onCreateFunction. Observe que o nome pode ser qualquer coisa; você só precisa defini-lo no projeto do complemento do manifesto.

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 de sistema de terceiros. Estes recursos não foram implementados aqui, já que dependem muito dos detalhes do sistema de terceiros.

A função initializeSyncing() não é mostrada aqui. ele lida com questões preliminares, o trabalho necessário para a sincronização. Consulte Sincronizar as alterações da 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;
}