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

Cette page explique comment utiliser l'API Google Agenda pour créer des événements qui affichent l'état des utilisateurs de Google Agenda. Les événements d'état décrivent l'emplacement ou l'activité des utilisateurs, y compris s'ils sont en mode concentration, absents du bureau ou en télétravail depuis un certain lieu.

Dans Google Agenda, les utilisateurs peuvent créer des événements "Moment de concentration", "Absent" et "Lieu de travail" pour indiquer leur disponibilité et leur lieu 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 lister les événements d'état de l'agenda

Vous pouvez lire et lister les événements d'état 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 l'eventId de l'événement.

Pour lister 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 consultez le champ correspondant pour en savoir plus sur l'état créé par l'utilisateur dans Google Agenda:

S'abonner aux modifications des événements d'état

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

Utilisez la méthode events.watch, en spécifiant l'calendarId du calendrier 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 d'état de 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éer 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 comme événement temporisé (avec les heures de début et de fin spécifiées).
    Les moments de concentration ne peuvent pas être des événements d'une journée complète.

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

Créer un message d'absence

Pour créer un événement d'absence:

  • 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 comme un événement temporisé (avec les heures de début et de fin spécifiées).
    Les événements d'absence du bureau ne peuvent pas être des événements d'une journée complète.

Pour en savoir plus sur cette fonctionnalité, consultez Afficher l'option "Disponibilité".

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:

    • Un événement programmé (avec des heures de début et de fin spécifiées) ;
    • Événement qui dure toute la journée (avec des dates de début et de fin spécifiées) et qui s'étend sur exactement un jour.

    Les événements d'une journée entière associés à un lieu de travail ne peuvent pas s'étendre sur plusieurs jours, mais les événements programmés peuvent le faire.

Les champs suivants sont facultatifs, mais recommandés pour une expérience utilisateur optimale lors de l'insertion d'un officeLocation:

La création et la mise à jour d'événements de lieu de travail via les points de terminaison de traitement par lot ne sont pas prises en charge.

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

Afficher des é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 qui se chevauchent, ce qui signifie qu'à un moment donné, plusieurs lieux de travail peuvent être définis. Lorsque seul un seul lieu peut être présenté à l'utilisateur, celui-ci doit être affiché de manière cohérente dans plusieurs applications. Pour ce faire, suivez les consignes ci-dessous afin de choisir l'événement à afficher:

  • Les événements programmés ont la priorité sur les événements d'une journée entière.
  • Les événements uniques ont la priorité sur les événements récurrents et leurs exceptions.
  • Les événements qui commencent plus tard ont la priorité sur ceux qui commencent plus tôt.
  • Les événements de durée plus courte prévalent sur ceux de durée plus longue.
  • Les événements créés plus récemment prévalent sur ceux créés plus tôt.
  • Les événements partiellement chevauchants doivent être affichés en tant que deux événements distincts, chacun avec son 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 intégrables à Google Workspace. Les scripts sont développés dans un éditeur de code basé sur un navigateur, et ils sont stockés et exécutés sur les serveurs de Google. Consultez également le démarrage rapide Google Apps Script pour commencer à utiliser Apps Script pour envoyer des requêtes à l'API Google Agenda.

Les instructions suivantes décrivent comment gérer les événements d'état à l'aide de l'API Google Agenda 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 Agenda, consultez la documentation de référence.

Créer et configurer le script

  1. Créez un script en accédant à script.google.com/create.
  2. Dans le panneau de gauche, à côté de Services, cliquez sur Ajouter un service  .
  3. Sélectionnez API Google Agenda, puis cliquez sur Ajouter.
  4. Une fois activée, l'API apparaît dans le volet de gauche. Vous pouvez lister les méthodes et classes disponibles dans l'API à l'aide du mot clé 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. Sur le côté 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 participant au programme Preview développeur, puis cliquez sur Définir le projet.
  4. Sur la 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 lister 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 Run (Exécuter).
  2. Lors de la première exécution, vous êtes invité à autoriser l'accès. Examinez les autorisations 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 s'affiche en bas de la fenêtre.