Création de conférences tierces

classe

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é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 toutes les informations d'événement Google Agenda, telles que l'ID d'é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 conférence tiers et créez-y une conférence à l'aide des informations d'événement de Google Agenda.
  3. Si la demande de création de conférence échoue pour une raison quelconque, utilisez les informations d'erreur pour créer et renvoyer un objet ConferenceData contenant un ConferenceError. Sinon, passez aux é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, vous devez fournir certaines informations sur l'événement Google Agenda correspondant. Les informations exactes requises sur l'événement varient d'un système de conférence tiers à un autre, mais elles incluent souvent l'heure de début, l'heure de fin, le résumé, la liste des participants et l'ID de l'événement.

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

Google Agenda peut ajouter les détails d'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 seront remplacées lors de la prochaine synchronisation de l'événement.

Création de 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, vous devez généralement envoyer 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 API que vous pouvez utiliser pour créer des conférences.

Dans Apps Script, le moyen le plus simple de gérer des requêtes 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 cela nécessite que vous gériez explicitement les détails d'autorisation.

Après avoir demandé la création d'une conférence, vous devrez peut-être envoyer 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, il doit suivre quelques étapes pour activer la synchronisation afin que les modifications apportées à l'événement Google Agenda soient répercutées dans la conférence.

Pour en savoir plus sur la configuration de la synchronisation après la création d'une conférence, consultez la page Synchroniser les modifications apportées à Agenda.

Créer une réponse basée sur les données pour une 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 certaines limites concernant la longueur des champs, le format des URI de point d'entrée et les combinaisons de points d'entrée autorisées. Par exemple, il peut y avoir au maximum un point d'entrée VIDEO dans une même ConferenceData. Ces limites sont identiques à celles décrites dans la section Événement de l'API Calendar pour le champ conferenceData correspondant, bien que les champs d'événement d'API décrits ne soient pas tous disponibles dans Apps Script.

Traiter les erreurs

Dans certains cas, la création de la conférence ne peut pas être terminé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 efficacement la condition d'erreur en créant et en renvoyant un objet ConferenceData contenant les détails de 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 comporter un ConferenceErrorType, un message d'erreur et, en cas de problèmes d'authentification, une URL permettant aux utilisateurs de se connecter au système de conférence tiers.

Exemple

Vous trouverez ci-dessous un exemple de onCreateFunction (notez que vous pouvez attribuer n'importe quel nom à la fonction. 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. Elles ne sont pas pleinement implémentées ici, car elles dépendent fortement des détails du système tiers.

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