Se usó la API de Cloud Translation para traducir esta página.

Creación de conferencias de terceros

Cada solución de conferencia que definiste en el manifiesto de tu proyecto de secuencia de comandos 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 de conferencia para un evento.

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

Recuperar cualquier información del evento del Calendario de Google, como el ID del evento o la lista de asistentes, que el sistema de conferencias de terceros pueda necesitar para crear la conferencia
Conéctate al servicio de conferencias de terceros y crea una nueva conferencia allí con la información del evento del Calendario de Google.
Si la solicitud de creación de la conferencia falló por algún motivo, usa la información del error para compilar y devolver un objeto ConferenceData que contenga un ConferenceError. De lo contrario, completa los siguientes pasos.
1. Inicializa la sincronización de la conferencia.
2. Usa la información que devuelve el servicio de conferencias de terceros para compilar y devolver un nuevo objeto ConferenceData.

Recuperando información del evento

Para crear una conferencia de terceros, se necesita cierta información sobre el evento correspondiente del Calendario de Google. La información exacta del evento que se requiere varía entre los diferentes sistemas de conferencias de terceros, pero, a menudo, incluye la hora de inicio, la hora de finalización, el resumen, la lista de asistentes y el ID del evento.

Cuando se llama, cada onCreateFunction que defines recibe un argumento que contiene los IDs del calendario y del evento. Puedes usar estos IDs para recuperar la información completa del evento con el servicio avanzado de Calendario de Google.

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

Cómo crear la conferencia de terceros

Una vez que onCreateFunction recuperó los datos del evento necesarios, debe conectarse al sistema de conferencias de terceros para crear la conferencia. Por lo general, esto se logra haciendo solicitudes a la API compatibles con el sistema de conferencias de terceros. Consulta la documentación de tu solución de conferencias de terceros para determinar qué solicitudes de API puedes usar para crear conferencias.

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

Después de solicitar la creación de la conferencia, es posible que debas realizar solicitudes adicionales para recuperar los detalles de la nueva conferencia.

Inicializa la sincronización de la conferencia

Una vez que el complemento haya creado correctamente una conferencia en un sistema de terceros, se deben seguir algunos pasos para habilitar la sincronización, de modo que los cambios en el evento de Calendario de Google se reflejen en la conferencia.

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

Cómo crear una respuesta de datos de conferencia

Con la información de la conferencia que devuelve el servicio de terceros, el objeto onCreateFunction debe compilar y devolver un objeto ConferenceData. En la sección Datos de la conferencia, se describe el contenido de este objeto. Calendario de Google usa esta información para dirigir a los usuarios a la conferencia una vez que comienza.

Cuando compiles un objeto ConferenceData, ten en cuenta que existen algunas limitaciones en las longitudes de los campos, los formatos de los URIs de los puntos de entrada y las combinaciones permitidas de puntos de entrada. Por ejemplo, puede haber como máximo un punto de entrada VIDEO en un solo ConferenceData. Estas limitaciones son idénticas a las que se describen en el objeto Event de la API de Calendar](/workspace/calendar/v3/reference/events) para el campo conferenceData correspondiente, aunque no todos los campos del objeto Event de la API que se describen allí están disponibles en Apps Script.

Maneja los errores

En algunos casos, no se puede completar la creación de la conferencia debido a un error que muestra el sistema de conferencias de terceros. En estos casos, tu complemento debe controlar de forma sólida la condición de error creando y devolviendo un objeto ConferenceData que contenga detalles de ConferenceError, de modo que el Calendario de Google pueda actuar en consecuencia.

Cuando construyas un objeto ConferenceData para informar un error, no es necesario que incluyas ningún componente ConferenceData, excepto el objeto ConferenceError. ConferenceErrors puede tener un ConferenceErrorType, un mensaje de error y, en el caso de problemas de autenticación, una URL que permita a los usuarios acceder al sistema de conferencias de terceros.

Ejemplo

A continuación, se muestra un ejemplo de un onCreateFunction (ten en cuenta que el nombre de la función puede ser cualquiera; solo debes definirlo en el manifiesto del proyecto del complemento).

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

Aquí no se muestra la función initializeSyncing(), ya que controla cualquier trabajo preliminar necesario para la sincronización. Consulta Cómo sincronizar los cambios del calendario para obtener más 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;
}