Gérer les événements "Moment de concentration", "Absent du bureau" et "Lieu de travail"

Cette page explique comment utiliser l'API Google Calendar pour créer des événements indiquant l'état des utilisateurs de Google Agenda. Les événements d'état décrivent où se trouvent les utilisateurs ou ce qu'ils font, y compris s'ils sont en "Moment de concentration", s'ils sont absents ou s'ils travaillent à un certain endroit.

Dans Google Agenda, les utilisateurs peuvent créer des événements "Moment de concentration", "Absent du bureau" et "Lieu de travail" pour indiquer leur état et leur lieu de travail personnalisés. Ces fonctionnalités ne sont disponibles que dans les agendas principaux, et pour certains utilisateurs de Google Agenda.

Pour en savoir plus, consultez Utiliser les moments de concentration dans Google Agenda et Activer ou désactiver le lieu de travail pour les utilisateurs.

Lire et répertorier les événements de disponibilité dans l'agenda

Vous pouvez consulter et répertorier les événements de disponibilité de l'agenda dans la ressource Events de l'API Calendar.

Pour lire un événement d'état, utilisez la méthode events.get, en spécifiant la valeur eventId de l'événement.

Pour répertorier les événements d'état, utilisez la méthode events.list, en spécifiant une ou plusieurs des valeurs suivantes dans le champ eventTypes:

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

Ensuite, dans les objets Event renvoyés, vérifiez que le champ eventType contient la valeur demandée, puis reportez-vous au champ correspondant pour en savoir plus sur l'état créé par l'utilisateur dans Google Agenda:

S'abonner aux modifications apportées aux événements d'état

Vous pouvez vous abonner aux modifications des événements d'état dans la ressource Events de l'API Calendar.

Utilisez la méthode events.watch, en spécifiant le calendarId de l'agenda auquel vous souhaitez vous abonner et une ou plusieurs des valeurs suivantes dans le champ eventTypes:

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

Créer et mettre à jour des événements de disponibilité dans l'agenda

Pour créer un événement d'état, vous devez créer une instance de la ressource Events à l'aide de la méthode events.insert, en définissant les champs obligatoires pour le type d'événement.

Si vous mettez à jour l'événement d'état à l'aide de la méthode events.update, l'événement doit conserver les champs obligatoires.

Créez un moment de concentration

Pour créer un événement "Moment de concentration" :

  • Définissez eventType sur 'focusTime'.
  • Incluez le champ focusTimeProperties.
  • Définissez le champ transparency sur 'opaque'.
  • Définissez les champs start et end de l'événement sur un événement minuté (avec des heures de début et de fin spécifiées).
    Les moments de concentration ne peuvent pas durer toute une journée.

Pour en savoir plus sur les fonctionnalités, consultez Utiliser les moments de concentration dans Google Agenda.

Créer une absence du bureau

Pour créer une absence du bureau:

  • Définissez eventType sur 'outOfOffice'.
  • Incluez le champ outOfOfficeProperties.
  • Définissez le champ transparency sur 'opaque'.
  • Définissez les champs start et end de l'événement sur un événement minuté (avec des heures de début et de fin spécifiées).
    Les absences du bureau ne peuvent pas durer toute la journée.

Pour en savoir plus sur les fonctionnalités, consultez Indiquer quand vous êtes absent.

Créer un lieu de travail

Pour créer un événement de lieu de travail:

  • Définissez eventType sur 'workingLocation'.
  • Incluez le champ workingLocationProperties.
  • Définissez le champ visibility sur 'public'.
  • Définissez le champ transparency sur 'transparent'.
  • Définissez les champs start et end de l'événement sur l'un des champs suivants:

    • Un événement programmé (avec des heures de début et de fin spécifiées)
    • Événement d'une journée (avec des dates de début et de fin spécifiées) qui s'étendent exactement sur une journée.

    Les événements de lieu de travail d'une journée ne peuvent pas s'étendre sur plusieurs jours, contrairement aux événements temporisés.

Les champs suivants sont facultatifs, mais recommandés pour une expérience utilisateur optimale lorsque vous insérez un officeLocation:

Il n'est pas possible de créer ni de mettre à jour des événements de lieu de travail via les points de terminaison de traitement par lot.

Pour en savoir plus sur les fonctionnalités, consultez Définir vos heures et votre lieu de travail et Activer ou désactiver le lieu de travail pour les utilisateurs.

Afficher les événements de lieu de travail qui se chevauchent

Un utilisateur peut avoir plusieurs événements de lieu de travail dans son agenda en même temps, ce qui se chevauchent. Cela signifie que plusieurs lieux de travail peuvent être définis pour une même heure. Dans les cas où un seul établissement peut être présenté à l'utilisateur, celui-ci doit l'être de manière cohérente dans plusieurs applications. Lors de cette opération, suivez les consignes ci-dessous pour choisir l'événement à afficher:

  • Les événements planifiés sont prioritaires sur les événements d'une journée entière.
  • Les événements individuels prévalent sur les événements périodiques et leurs exceptions.
  • Les événements démarrant à une date ultérieure prévalent sur ceux débutés plus tôt.
  • Les événements d'une durée plus courte sont prioritaires sur ceux dont la durée est plus longue.
  • Les événements créés plus récemment prévalent sur ceux créés précédemment.
  • Les événements qui se chevauchent partiellement doivent être affichés sous la forme de deux événements différents ayant chacun leur propre lieu de travail.

Créer des événements d'état dans Google Apps Script

Google Apps Script est un langage de script cloud basé sur JavaScript qui vous permet de créer des applications professionnelles qui s'intègrent à Google Workspace. Les scripts sont développés dans un éditeur de code basé sur un navigateur. Ils sont stockés et exécutés sur les serveurs de Google. Consultez également le guide de démarrage rapide de Google Apps Script pour commencer à utiliser Apps Script pour envoyer des requêtes à l'API Google Calendar.

Les instructions suivantes décrivent comment gérer les événements d'état à l'aide de l'API Google Calendar en tant que service avancé dans Google Apps Script. Pour obtenir la liste complète des ressources et des méthodes de l'API Google Calendar, consultez la documentation de référence.

Créer et configurer le script

  1. Accédez à script.google.com/create pour créer un script.
  2. Dans le volet de gauche, à côté de Services, cliquez sur Ajouter un service .
  3. Sélectionnez API Google Calendar, puis cliquez sur Ajouter.
  4. Une fois activée, l'API apparaît dans le volet de gauche. Les classes et méthodes disponibles dans l'API peuvent être listées à l'aide du mot clé Calendar (Agenda) dans l'éditeur.

(Facultatif) Mettre à jour le projet Google Cloud

Chaque projet Google Apps Script est associé à un projet Google Cloud. Votre script peut utiliser le projet par défaut créé automatiquement par Google Apps Script. Si vous souhaitez utiliser un projet Google Cloud personnalisé, procédez comme suit pour mettre à jour le projet associé à votre script.

  1. À gauche de l'éditeur, cliquez sur Paramètres du projet .
  2. Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.
  3. Saisissez le numéro du projet Google Cloud figurant dans le programme Preview développeur, puis cliquez sur Définir un projet.
  4. Sur le côté gauche, sélectionnez Éditeur pour revenir à l'éditeur de code.

Ajouter du code au script

L'exemple de code suivant montre comment créer, lire et répertorier des événements d'état dans votre agenda principal.

  1. Collez le code suivant dans l'éditeur de code.

    /** Creates a focus time event. */
    function createFocusTime() {
      const event = {
        start: { dateTime: '2023-11-14T10:00:00+01:00' },
        end: { dateTime: '2023-11-14T12:00:00+01:00' },
        eventType: 'focusTime',
        focusTimeProperties: {
          chatStatus: 'doNotDisturb',
          autoDeclineMode: 'declineOnlyNewConflictingInvitations',
          declineMessage: 'Declined because I am in focus time.',
        }
      }
      createEvent(event);
    }
    
    /** Creates an out of office event. */
    function createOutOfOffice() {
      const event = {
        start: { dateTime: '2023-11-15T10:00:00+01:00' },
        end: { dateTime: '2023-11-15T18:00:00+01:00' },
        eventType: 'outOfOffice',
        outOfOfficeProperties: {
          autoDeclineMode: 'declineOnlyNewConflictingInvitations',
          declineMessage: 'Declined because I am on vacation.',
        }
      }
      createEvent(event);
    }
    
    /** Creates a working location event. */
    function createWorkingLocation() {
      const event = {
        start: { date: "2023-06-01" },
        end: { date: "2023-06-02" },
        eventType: "workingLocation",
        visibility: "public",
        transparency: "transparent",
        workingLocationProperties: {
          type: 'customLocation',
          customLocation: { label: "a custom location" },
        }
      }
      createEvent(event);
    }
    
    /**
      * Creates a Calendar event.
      * See https://developers.google.com/calendar/api/v3/reference/events/insert
      */
    function createEvent(event) {
      const calendarId = 'primary';
    
      try {
        var response = Calendar.Events.insert(event, calendarId);
        var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
        console.log(event);
      } catch (exception) {
        console.log(exception.message);
      }
    }
    
    /**
      * Reads the event with the given eventId.
      * See https://developers.google.com/calendar/api/v3/reference/events/get
      */
    function readEvent() {
      const calendarId = 'primary';
    
      // Replace with a valid eventId.
      const eventId = "sample-event-id";
    
      try {
        var response = Calendar.Events.get(calendarId, eventId);
        var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
        console.log(event);
      } catch (exception) {
        console.log(exception.message);
      }
    }
    
    /** Lists focus time events. */
    function listFocusTimes() {
      listEvents('focusTime');
    }
    
    /** Lists out of office events. */
    function listOutOfOffices() {
      listEvents('outOfOffice');
    }
    
    /** Lists working location events. */
    function listWorkingLocations() {
      listEvents('workingLocation');
    }
    
    /**
      * Lists events with the given event type.
      * See https://developers.google.com/calendar/api/v3/reference/events/list
      */
    function listEvents(eventType = 'default') {
      const calendarId = 'primary'
    
      // Query parameters for the list request.
      const optionalArgs = {
        eventTypes: [eventType],
        showDeleted: false,
        singleEvents: true,
        timeMax: '2023-04-01T00:00:00+01:00',
        timeMin: '2023-03-27T00:00:00+01:00',
      }
      try {
        var response = Calendar.Events.list(calendarId, optionalArgs);
        response.items.forEach(event =>
          console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
      } catch (exception) {
        console.log(exception.message);
      }
    }
    
    /**
      * Parses working location properties of an event into a string.
      * See https://developers.google.com/calendar/api/v3/reference/events#resource
      */
    function parseWorkingLocation(event) {
      if (event.eventType != "workingLocation") {
        throw new Error("'" + event.summary + "' is not a working location event.");
      }
    
      var location = 'No Location';
      const workingLocation = event.workingLocationProperties;
      if (workingLocation) {
        if (workingLocation.type === 'homeOffice') {
          location = 'Home';
        }
        if (workingLocation.type === 'officeLocation') {
          location = workingLocation.officeLocation.label;
        }
        if (workingLocation.type === 'customLocation') {
          location = workingLocation.customLocation.label;
        }
      }
      return `${event.start.date}: ${location}`;
    }
    

Exécuter l'exemple de code

  1. Au-dessus de l'éditeur de code, sélectionnez la fonction à exécuter dans le menu déroulant, puis cliquez sur Exécuter.
  2. Lors de la première exécution, vous êtes invité à autoriser l'accès. Examinez et autorisez Apps Script à accéder à votre agenda.
  3. Vous pouvez inspecter les résultats de l'exécution du script dans le journal d'exécution qui apparaît au bas de la fenêtre.