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

Créer des conférences tierces

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

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érer toutes les informations d'événement Google Agenda, telles que l'ID de l'événement ou liste des participants, dont le système de conférence tiers peut avoir besoin pour créer la conférence.
Se connecter au service de conférence tiers et créer une conférence à l'aide des informations sur les événements Google Agenda.
Si la demande de création de conférences a échoué pour une raison quelconque, utilisez l'erreur pour créer et renvoyer 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 conférence tiers pour de créer et de renvoyer ConferenceData .

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

Pour créer une conférence tierce, vous devez fournir certaines informations Un événement Google Agenda est requis. Les informations exactes sur l'événement requises varient entre différents systèmes de conférence tiers, mais cela inclut souvent l'heure de début et de fin de l'événement, le résumé, la liste des participants et l'identifiant.

Lorsqu'elle est appelée, chaque onCreateFunction que vous définissez reçoit un argument qui contient les ID de l'agenda et des événements. Vous pouvez utiliser ces identifiants pour récupérer toutes les informations sur l'événement à l'aide de la méthode Service avancé Google Agenda :

Google Agenda peut ajouter des informations sur une conférence à un événement avant le qu'elle existe. Dans ce cas, Google Agenda transmet à onCreateFunction eventId, mais les appels suivants à Calendar.Events.get() peuvent entraîner une une réponse d'erreur indiquant que l'événement n'existe pas. Dans ces 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 Synchronisations

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, vous devez généralement exécuter des requêtes API système de conférence tiers. Consultez la documentation de votre fournisseur tiers de conférence pour déterminer quelles requêtes API vous pouvez utiliser pour créer conférences.

Dans Apps Script, le moyen le plus simple de créer des requêtes API externes est de à l'aide du protocole OAuth2 pour Apps Script, ou OAuth1 pour Apps Script Open Source. Vous pouvez également se connecter à des API externes à l'aide du service UrlFetch mais cela vous oblige à gérer les détails de l'autorisation explicitement.

Après avoir demandé la création de la conférence, vous devrez peut-être effectuer des pour récupérer les informations sur 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, vous devez suivre quelques étapes syncing pour que les modifications l'événement Google Agenda sont reflétés pendant la conférence.

Consultez Synchronisation des 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 une ConferenceData objet ; la Données sur la conférence décrit le contenu de cet objet. Google Agenda utilise utilise ces informations pour diriger les utilisateurs vers la conférence une fois qu'elle a commencé.

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

Traiter les erreurs

Dans certains cas, il est impossible de créer la conférence, car d'une erreur renvoyée par le système de conférence tiers. Dans ces cas-là votre module complémentaire doit gérer efficacement la condition d'erreur en créant et en renvoyant un ConferenceData objet contenant ConferenceError détails, afin que Google Agenda puisse agir en conséquence.

Lorsque vous créez un objet ConferenceData pour signaler une erreur, vous n'avez pas à devez inclure tous les composants ConferenceData en dehors de ConferenceError. ConferenceErrors peut avoir un ConferenceErrorType, un message d'erreur et, dans le cas de problèmes d'authentification, une URL qui permet aux utilisateurs de se connecter au système de conférence tiers.

Exemple

Voici un exemple de onCreateFunction (notez que le nom du peut être n'importe quelle valeur ; il suffit de le définir dans votre projet de module complémentaire fichier manifeste).

La fonction create3rdPartyConference() contacte le système tiers pour créer la conférence à cet endroit et la fonction getAuthenticationUrl() crée une URL d'authentification de système tiers. Elles ne sont pas implémentées car ils dépendent fortement des détails du système tiers.

La fonction initializeSyncing() n'est pas présentée ici. il gère toutes les étapes préliminaires travail requis pour la synchronisation. Consultez Synchroniser les modifications apportées à l'agenda. pour en savoir plus.

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