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 que vous avez définie dans le manifeste de votre projet de script est associée à un onCreateFunction. Le module complémentaire 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.

Vous devez implémenter chaque onCreateFunction décrit dans le fichier manifeste de votre module complémentaire. En général, 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 peut avoir 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 Google Agenda.
3. Si la demande de création de la conférence a échoué pour une raison quelconque, utilisez les informations sur l'erreur pour créer et renvoyer un objet ConferenceData contenant un ConferenceError. Sinon, suivez les étapes suivantes.
   1. Initialisez la synchronisation des conférences.
   2. 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 conférence tierce, certaines informations sur l'événement Google Agenda correspondant sont nécessaires. Les informations exactes requises sur l'événement varient selon les systèmes de conférence tiers. Toutefois, elles 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. Vous pouvez utiliser ces ID pour récupérer les informations complètes sur l'événement à l'aide du service avancé Google Agenda.

Il est possible que Google Agenda ajoute des informations de conférence à un événement avant qu'il n'existe. Dans ce cas, Google Agenda transmet le onCreateFunction à un eventId valide, mais les appels suivants à Calendar.Events.get() peuvent générer une réponse d'erreur indiquant que l'événement n'existe pas. Dans ce cas, il est préférable de créer la visioconférence tierce à l'aide de données d'espace réservé. Ces données sont remplacées la prochaine fois que l'événement est 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 visioconférence tiers pour créer la visioconfé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 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 visioconférence dans un système tiers, il doit suivre quelques étapes pour activer la synchronisation afin que les modifications apportées à l'événement Google Agenda soient reflétées dans la visioconfé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. Google 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, sachez qu'il existe des limites concernant la longueur des champs, les formats des URI de points d'entrée et les 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 la documentation de référence sur les événements de l'API Calendar pour le champ conferenceData correspondant. Toutefois, tous les champs d'événement de l'API décrits dans cette documentation ne sont pas disponibles dans Apps Script.

Traiter les erreurs

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 l'état d'erreur de manière robuste en créant et en renvoyant un objet ConferenceData contenant des détails ConferenceError, afin que Google 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 élément 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 visioconférence tiers.

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

Exemple

L'exemple suivant montre un onCreateFunction (notez que le nom de la fonction peut être n'importe quel nom. Vous n'avez qu'à le définir dans le fichier manifeste de votre projet de module complémentaire).

La fonction create3rdPartyConference() contacte le système tiers pour y 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, car elles dépendent fortement des détails du système tiers.

La fonction initializeSyncing() n'est pas affichée ici. Elle gère toutes les tâches préliminaires requises 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;
}