Creación de conferencias de terceros

Cada solución para conferencias que definiste en tu proyecto de secuencia de comandos manifiesto tiene un onCreateFunction asociado. El complemento llama a esta función para crear una conferencia cada vez que un usuario intenta seleccionar esa solución, un para cada evento.

Debes implementar cada onCreateFunction que se describe en el manifiesto del complemento. En general, estas funciones deben hacer lo siguiente:

  1. Recuperar la información de cualquier evento del Calendario de Google, como el ID del evento o de asistentes que necesite el sistema de conferencias de terceros para crear la conferencia.
  2. Conéctate al servicio de conferencias de terceros y crea una nueva allí usando la información del evento del Calendario de Google.
  3. Si por algún motivo falla la solicitud de creación de conferencia, utiliza el mensaje de información para crear y devolver un ConferenceData objeto que contiene un ConferenceError De lo contrario, completa los pasos siguientes.
    1. Inicializa la sincronización de la conferencia.
    2. Usa la información que devuelve el servicio de reuniones de terceros para lo siguiente: compilar y devolver un nuevo ConferenceData .

Recuperar información de eventos

Para crear una conferencia de terceros, cierta información sobre la reunión Se necesita un evento de Calendario de Google. La información exacta requerida del evento varía entre diferentes sistemas de conferencias de terceros, aunque, a menudo, esto incluye hora de inicio, hora de finalización, resumen, ID y lista de asistentes.

Cuando se llama, cada onCreateFunction que defines recibe un argumento que contiene los IDs de calendario y de eventos. Puedes usarlos para recuperar las la información completa del evento Servicio avanzado de Calendario de Google.

Es posible que el Calendario de Google agregue detalles de la conferencia a un evento antes de existe. En esos casos, el Calendario de Google pasa el onCreateFunction un eventId, pero las llamadas posteriores a Calendar.Events.get() pueden generar una respuesta de error que indica que el evento no existe. En estos casos, es mejor crear la conferencia de terceros con datos de marcador de posición; estos datos se reemplazan la próxima vez que el evento sincronizaciones.

Creando la conferencia de terceros

Una vez que onCreateFunction haya recuperado los datos de eventos necesarios, debe conectarte al sistema de reuniones de terceros para crearla. Normalmente, esto se logra mediante solicitudes a la API que admite el un sistema de conferencias de terceros. Consulta la documentación de los recursos de la de Google Cloud para determinar qué solicitudes a la API puedes usar para crear individuales.

En Apps Script, la forma más fácil de controlar la realización de solicitudes externas a la API es con OAuth2 para Apps Script o bien OAuth1 para Apps Script bibliotecas de código abierto. También puedes conectarte a APIs externas con el servicio UrlFetch pero esto requiere que maneje los detalles de autorización explícitamente.

Luego de solicitar la creación de la conferencia, es posible que debas hacer las solicitudes para recuperar los nuevos detalles de la conferencia.

Inicializa la sincronización de conferencias

Después de que el complemento haya creado correctamente una conferencia en un sistema de terceros, debes seguir algunos pasos para habilitar sincronización para que cambie el evento de Calendario de Google se reflejan en la conferencia.

Consulta Cómo sincronizar los cambios del Calendario para obtener detalles sobre cómo configurar la sincronización después de crear la conferencia.

Crear una respuesta de datos de conferencia

Con la información de conferencia que devuelve el servicio de terceros, Luego, onCreateFunction debe compilar y mostrar un ConferenceData object; el Datos de conferencias describe el contenido de este objeto. El Calendario de Google usa utiliza esta información para dirigir a los usuarios a la conferencia una vez que comienza.

Cuando compilas un ConferenceData ten en cuenta que existen algunas limitaciones en cuanto a las longitudes de campo, los formatos de los URI de punto de entrada y las combinaciones permitidas de puntos de entrada. Por ejemplo: puede haber como máximo un punto de entrada VIDEO en una sola ConferenceData Estas limitaciones son idénticas a las que se describen en el evento de la API de Calendar del evento correspondiente conferenceData, aunque no todos los campos de eventos de la API que se describen allí están disponibles en Apps Script.

Maneja los errores

En algunos casos, la creación de la conferencia no se puede completar porque de un error que muestra el sistema de conferencias de terceros. En estos casos, tu complemento debe manejar con solidez la condición de error compilando y para mostrar un ConferenceData objeto que contiene ConferenceError a fin de que el Calendario de Google pueda actuar en consecuencia.

Cuando construyes un objeto ConferenceData para informar un error, no debes hacer lo siguiente: deberás incluir cualquier componente ConferenceData además del ConferenceError. ConferenceErrors puede tener un ConferenceErrorType, mensaje de error y, en el caso de problemas de autenticación, una URL que permita que los usuarios accedan al sistema de conferencias de terceros.

Ejemplo

A continuación, se muestra un ejemplo de un onCreateFunction (ten en cuenta que el nombre del función puede ser cualquier cosa; solo tienes que definirla en tu proyecto de complemento de Terraform).

La función create3rdPartyConference() se comunica con el sistema de terceros para crear la conferencia allí y la función getAuthenticationUrl() crea una URL de autenticación del sistema de terceros. Estos no se implementaron ya que dependen en gran medida de los detalles del sistema de terceros.

La función initializeSyncing() no se muestra aquí. se encarga de las tareas preliminares trabajo requerido para la sincronización. Consulta Cómo sincronizar cambios del calendario. para conocer los detalles.

/**
 *  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;
}