Creazione di conferenze di terze parti

Nota: questa funzionalità è stata creata appositamente per i provider di conferenze ed era originariamente disponibile come componenti aggiuntivi per le conferenze tramite calendario.

Ogni soluzione per conferenze che hai definito nel manifest del progetto di script ha un onCreateFunction associato. Il componente aggiuntivo chiama questa funzione per creare una conferenza ogni volta che un utente tenta di selezionare la soluzione di conferenza per un evento.

Devi implementare ogni onCreateFunction descritto nel manifest del componente aggiuntivo. In generale, queste funzioni devono:

1. Recuperare le informazioni sugli eventi di Google Calendar, ad esempio l'ID evento o l'elenco dei partecipanti, di cui il sistema di conferenze di terze parti potrebbe aver bisogno per creare la conferenza.
2. Connettiti al servizio di videoconferenza di terze parti e crea una nuova conferenza utilizzando le informazioni sull'evento di Google Calendar.
3. Se la richiesta di creazione della conferenza non è andata a buon fine per qualche motivo, utilizza le informazioni di errore per creare e restituire un oggetto ConferenceData contenente un ConferenceError. In caso contrario, completa i passaggi successivi.
   1. Inizializza la sincronizzazione della conferenza.
   2. Utilizza le informazioni restituite dal servizio di videoconferenze di terze parti per costruire e restituire un nuovo oggetto ConferenceData.

Recupero delle informazioni sugli eventi

Per creare una conferenza di terze parti, sono necessarie alcune informazioni sull'evento corrispondente di Google Calendar. Le informazioni esatte richieste per l'evento variano tra i diversi sistemi di conferenze di terze parti, ma spesso includono l'ora di inizio e di fine dell'evento, il riepilogo, l'elenco dei partecipanti e l'ID.

Quando viene chiamato, a ogni onCreateFunction che definisci viene passato un argomento che contiene gli ID calendario ed evento. Puoi utilizzare questi ID per recuperare le informazioni complete sugli eventi utilizzando il servizio avanzato di Google Calendar.

È possibile che Google Calendar aggiunga i dettagli della conferenza a un evento prima che esista. In questi casi, Google Calendar passa a onCreateFunction un valore eventId valido, ma le chiamate successive a Calendar.Events.get() possono comportare una risposta di errore che indica che l'evento non esiste. In questi casi, è meglio creare la conferenza di terze parti utilizzando i dati segnaposto, che vengono sostituiti alla successiva sincronizzazione dell'evento.

Creazione della conferenza di terze parti

Una volta recuperati i dati necessari per l'evento, onCreateFunction deve collegarsi al sistema di videoconferenze di terze parti per creare la conferenza. In genere, questo viene fatto inviando richieste API supportate dal sistema di conferenze di terze parti. Consulta la documentazione della tua soluzione di conferenze di terze parti per determinare quali richieste API puoi utilizzare per creare conferenze.

In Apps Script, il modo più semplice per gestire le richieste all'API esterna è utilizzare le librerie open source OAuth2 per Apps Script o OAuth1 per Apps Script. Puoi anche connetterti ad API esterne utilizzando il servizio UrlFetch, ma devi gestire esplicitamente i dettagli di autorizzazione.

Dopo aver richiesto la creazione della conferenza, potrebbe essere necessario effettuare altre richieste per recuperare i dettagli della nuova conferenza.

Inizializzare la sincronizzazione della conferenza

Una volta che il componente aggiuntivo ha creato correttamente una conferenza su un sistema di terze parti, dovresti seguire alcuni passaggi per attivare la sincronizzazione in modo che le modifiche apportate all'evento di Google Calendar vengano applicate alla conferenza.

Per informazioni dettagliate sulla configurazione della sincronizzazione dopo la creazione della conferenza, consulta Sincronizzare le modifiche di Calendar.

Creazione di una risposta ai dati della conferenza

Utilizzando le informazioni sulla conferenza restituite dal servizio di terze parti, onCreateFunction deve quindi creare e restituire un oggetto ConferenceData. La sezione Dati della conferenza descrive i contenuti di questo oggetto. Google Calendar utilizza queste informazioni per indirizzare gli utenti alla conferenza una volta che è iniziata.

Quando crei un oggetto ConferenceData, tieni presente che esistono alcune limitazioni per le lunghezze dei campi, i formati degli URI dei punti di contatto e le combinazioni consentite di punti di contatto. Ad esempio, in un singolo ConferenceData può essere presente al massimo un punto di ingresso VIDEO. Queste limitazioni sono identiche a quelle descritte nell'evento dell'API Calendar per il campo conferenceData corrispondente, anche se non tutti i campi dell'evento dell'API descritti sono disponibili in Apps Script.

Gestione degli errori

In alcuni casi la creazione della conferenza non può essere completata a causa di un errore restituito dal sistema di conferenze di terze parti. In questi casi, il componente aggiuntivo deve gestire in modo affidabile la condizione di errore creando e restituendo un oggetto ConferenceData contenente dettagli ConferenceError, in modo che Google Calendar possa agire di conseguenza.

Quando crei un oggetto ConferenceData per segnalare un errore, non è necessario includere componenti ConferenceData diversi dall'oggetto ConferenceError. ConferenceErrors può avere un ConferenceErrorType, un messaggio di errore e, in caso di problemi di autenticazione, un URL che consente agli utenti di accedere al sistema di videoconferenze di terze parti.

Nota: il componente aggiuntivo non deve tentare di configurare la sincronizzazione delle conferenze se il tentativo di creazione della conferenza non è andato a buon fine.

Esempio

Di seguito è riportato un esempio di onCreateFunction (tieni presente che il nome della funzione può essere qualsiasi; devi solo definirlo nel manifest del progetto del componente aggiuntivo).

La funzione create3rdPartyConference() contatta il sistema di terze parti per creare la conferenza e la funzione getAuthenticationUrl() crea un URL di autenticazione del sistema di terze parti. Questi metodi non sono implementati completamente qui, in quanto dipendono molto dai dettagli del sistema di terze parti.

La funzione initializeSyncing() non è mostrata qui; gestisce eventuali operazioni preliminari necessarie per la sincronizzazione. Per maggiori dettagli, consulta Sincronizzare le modifiche al calendario.

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