Créer des conférences tierces

Remarque: Cette fonctionnalité a été conçue spécifiquement pour les fournisseurs de conférences et était initialement disponible sous forme de modules complémentaires de conférence de calendrier.

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

Vous devez implémenter chaque onCreateFunction décrite 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 toutes les informations sur l'événement Google Agenda, telles que l'ID de l'événement ou la liste des participants, dont le système de conférence tiers peut avoir besoin pour créer la conférence.
2. Connectez-vous au service de visioconférence tiers et créez une conférence à l'aide des informations de l'événement Google Agenda.
3. Si la requête de création de conférence a échoué pour une raison quelconque, utilisez les informations d'erreur pour créer et renvoyer un objet ConferenceData contenant un ConferenceError. Sinon, suivez les étapes suivantes.
   1. Initialisez la synchronisation de la conférence.
   2. Utilisez les informations renvoyées par le service de confé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 pour l'événement varient selon les systèmes de conférence tiers, mais incluent souvent l'heure de début et de fin de l'événement, le résumé, la liste des participants et l'ID.

Lors de l'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 sur une conférence à un événement avant qu'il n'existe. Dans ce cas, Google Agenda transmet à onCreateFunction un eventId valide, mais les appels ultérieurs à Calendar.Events.get() peuvent entraîner 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 confé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 conférence tiers pour créer la conférence. En règle générale, cela se fait en envoyant des requêtes API compatibles avec le système de conférence tiers. Consultez la documentation de votre solution de conférence tierce pour déterminer les requêtes d'API que vous pouvez utiliser pour créer des confé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 informations d'autorisation.

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

Initialiser la synchronisation de la conférence

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

Pour savoir comment configurer la synchronisation après la création de la conférence, consultez Synchroniser les modifications apportées à Agenda.

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

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

Lorsque vous créez un objet ConferenceData, gardez à l'esprit qu'il existe des limites concernant la longueur des champs, les formats des URI de point 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 l'événement de l'API Calendar pour le champ conferenceData correspondant, bien que tous les champs d'événement de l'API décrits ne soient 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 conférence tiers. Dans ce cas, votre module complémentaire doit gérer de manière robuste la condition d'erreur 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 en dehors de l'objet ConferenceError. ConferenceErrors peut contenir 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.

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

Exemple

Vous trouverez ci-dessous un exemple d'onCreateFunction (notez que le nom de la fonction peut être n'importe quoi. Il vous suffit de 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. Ils ne sont pas entièrement implémentés ici, car ils dépendent fortement des détails du système tiers.

La fonction initializeSyncing() n'est pas affichée ici. Elle gère tout travail préliminaire requis pour la synchronisation. Pour en savoir plus, consultez Synchroniser les modifications de 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;
}