Cette page a été traduite par l'API Cloud Translation.

Créer des conférences tierces

application

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 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:

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.
Connectez-vous au service de conférence tiers et créez-y une conférence à l'aide des informations de l'événement Google Agenda.
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, effectuez les étapes suivantes.
1. Initialisez la synchronisation de la conférence.
2. Utilisez les informations renvoyées par le service de visioconférence tiers pour créer et renvoyer un objet ConferenceData.

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

Pour créer une conférence tierce, vous avez besoin de 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 à l'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 de l'agenda et de l'événement. Vous pouvez utiliser ces ID pour récupérer toutes les informations sur les événements à l'aide du service avancé de Google Agenda.

Google Agenda peut ajouter des informations sur une conférence à un événement avant qu'il n'ait lieu. Dans ce cas, Google Agenda transmet à onCreateFunction un eventId valide, mais les appels suivants à 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é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 conférence. Pour ce faire, vous devez généralement envoyer des requêtes API compatibles avec le système de visioconfé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 les 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 de gérer explicitement les informations d'autorisation.

Après avoir demandé la création de la conférence, vous devrez peut-être envoyer des requêtes supplémentaires pour récupérer les nouvelles informations sur la 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, vous devez activer la synchronisation en quelques étapes afin que les modifications apportées à l'événement Google Agenda soient répercutées dans la conférence.

Consultez la section Synchroniser les modifications apportées à Agenda pour savoir comment configurer la synchronisation après la création d'une conférence.

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

À l'aide des informations sur la 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, sachez que la longueur des champs, les formats des URI de points d'entrée et les combinaisons de points d'entrée autorisées sont limités. Par exemple, il ne peut y avoir qu'un seul point d'entrée VIDEO par ConferenceData. Ces limitations sont identiques à celles décrites dans la section Événement de l'API Calendar pour le champ conferenceData correspondant, bien que tous les champs d'événement d'API qui y sont 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 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 avoir un ConferenceErrorType, un message d'erreur et, dans le cas de problèmes d'authentification, une URL permettant aux utilisateurs de se connecter au système de visioconférence tiers.

Exemple

Vous trouverez ci-dessous un exemple de onCreateFunction (notez que le nom de la fonction peut prendre n'importe quel nom. 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 pour ce système tiers. Elles ne sont pas complètement implémentées ici, car elles dépendent fortement des détails des systèmes tiers.

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