Créer des conférences tierces

Remarque : Cette fonctionnalité a été conçue spécifiquement pour les fournisseurs de services de conférence. Elle était initialement disponible sous la forme de modules complémentaires de visioconférence pour Agenda.

Chaque solution de visioconférence définie dans le manifeste de votre projet de script est associée à un onCreateFunction. Le module complémentaire Google Workspace appelle cette fonction pour créer une visioconférence chaque fois qu'un utilisateur tente de sélectionner cette solution de visioconférence pour un événement.

Implémentez chaque onCreateFunction décrit dans le fichier manifeste de votre module complémentaire. Ces fonctions doivent effectuer les opérations suivantes :

1. Récupérez les informations sur les événements Google Agenda (ID de l'événement ou liste des participants, par exemple) dont le système de visioconférence tiers a besoin pour créer la visioconférence.
2. Connectez-vous au service de visioconférence tiers et créez-y une visioconférence à l'aide des informations de l'événement Agenda.
3. Si la requête de création de la conférence échoue, utilisez les informations sur l'erreur pour créer et renvoyer un objet ConferenceData contenant un ConferenceError. Sinon, suivez les étapes suivantes.
4. Initialisez la synchronisation de la conférence.
5. Utilisez les informations renvoyées par le service de visioconférence tiers pour créer et renvoyer un nouvel objet ConferenceData.

Récupérer des informations sur un événement

Pour créer une visioconférence tierce, des informations sur l'événement Agenda correspondant sont nécessaires. Les informations exactes requises sur l'événement varient selon les systèmes de visioconférence tiers, mais incluent souvent l'heure de début et de fin de l'événement, son résumé, la liste des participants et son ID.

Lorsqu'il est appelé, chaque onCreateFunction que vous définissez reçoit un argument contenant les ID de l'agenda et de l'événement. Utilisez ces ID pour récupérer toutes les informations sur l'événement à l'aide du service avancé Agenda.

Il est possible qu'Agenda ajoute des informations de conférence à un événement avant qu'il n'existe. Dans ce cas, l'agenda transmet un eventId valide à onCreateFunction, mais les appels ultérieurs à Calendar.Events.get peuvent générer une erreur indiquant que l'événement n'existe pas. Dans ce cas, créez la visioconférence tierce à l'aide de données de substitution. Ces données seront remplacées la prochaine fois que l'événement sera synchronisé.

Créer la conférence tierce

Une fois que onCreateFunction a récupéré les données d'événement nécessaires, il doit se connecter au système de conférence tiers pour créer la conférence. Pour ce faire, il envoie généralement des requêtes API compatibles avec le système de visioconférence tiers. Consultez la documentation de votre solution de visioconférence tierce pour déterminer les requêtes API que vous pouvez utiliser pour créer des visioconférences.

Dans Google Apps Script, le moyen le plus simple de gérer les requêtes d'API externes consiste à utiliser les bibliothèques Open Source OAuth2 pour Apps Script ou OAuth1 pour Apps Script. Vous pouvez également vous connecter à des API externes à l'aide du service UrlFetch, mais vous devez gérer explicitement les détails d'autorisation.

Après avoir demandé la création de la conférence, vous devrez peut-être effectuer des demandes supplémentaires pour récupérer les détails de la nouvelle conférence.

Initialiser la synchronisation des conférences

Une fois que le module complémentaire a créé une conférence sur un système tiers, il faut suivre quelques étapes pour activer la synchronisation afin que les modifications apportées à l'événement Agenda soient reflétées dans la conférence.

Pour savoir comment configurer la synchronisation après la création d'une visioconférence, consultez Synchroniser les modifications apportées à l'agenda.

Créer une réponse de données de conférence

À l'aide des informations de la visioconférence renvoyées par le service tiers, le onCreateFunction doit ensuite créer et renvoyer un objet ConferenceData. La section Données de la visioconférence décrit le contenu de cet objet. Agenda utilise ces informations pour rediriger les utilisateurs vers la visioconférence une fois qu'elle a commencé.

Lorsque vous créez un objet ConferenceData, tenez compte de la longueur des champs, des formats des URI de point d'entrée et des combinaisons de points d'entrée autorisées. Par exemple, il ne peut y avoir qu'un seul point d'entrée VIDEO dans un seul ConferenceData. Ces limites sont identiques à celles décrites dans l'événement de l'API Calendar pour le champ conferenceData correspondant, bien que tous les champs d'événement de l'API qui y sont décrits ne soient pas disponibles dans Apps Script.

Gérer les erreurs

Des erreurs peuvent se produire lors de la création d'une conférence. Dans certains cas, la création de la conférence ne peut pas être effectuée en raison d'une erreur renvoyée par le système de visioconférence tiers. Dans ce cas, votre module complémentaire doit gérer la condition d'erreur en créant et en renvoyant un objet ConferenceData contenant des détails ConferenceError, afin que Agenda puisse agir en conséquence.

Lorsque vous créez un objet ConferenceData pour signaler une erreur, vous n'avez pas besoin d'inclure de composants ConferenceData, à l'exception de l'objet ConferenceError. ConferenceErrors peut comporter un ConferenceErrorType, un message d'erreur et, en cas de problème d'authentification, une URL permettant aux utilisateurs de se connecter au système de conférence tiers.

Votre module complémentaire n'a pas besoin d'essayer de configurer la synchronisation des conférences si la tentative de création de conférence a échoué.

Exemple

L'exemple suivant illustre une implémentation onCreateFunction. Vous pouvez donner le nom de votre choix à la fonction. Il vous suffit de la définir dans le fichier manifeste de votre projet de module complémentaire.

La fonction create3rdPartyConference contacte le système tiers pour créer la conférence, et la fonction getAuthenticationUrl crée une URL d'authentification du système tiers. Elles ne sont pas entièrement implémentées ici.

La fonction initializeSyncing n'est pas affichée ici. Elle gère le travail préliminaire requis pour la synchronisation. Pour en savoir plus, consultez Synchroniser les modifications apportées à l'agenda.

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