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 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 période de concentration, en congé ou s'ils travaillent 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 état 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 le 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 comporte la valeur demandée, puis consultez le champ correspondant pour obtenir des informations sur l'état créé par l'utilisateur dans Google Agenda :

S'abonner aux événements de changement 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 l'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 modifier des événements d'état 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 requis 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 sur "événement programmé" (avec des heures de début et de fin spécifiées).
    Les moments de concentration ne peuvent pas durer toute la journée.

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

Créer une absence du bureau

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 sur "événement programmé" (avec des heures de début et de fin spécifiées).
    Les événements d'absence du bureau ne peuvent pas durer toute la journée.

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 l'une des valeurs suivantes :

    • 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 dure exactement une journée.

    Les événements de lieu de travail "Toute la journée" ne peuvent pas s'étendre sur plusieurs jours, contrairement aux événements programmés.

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 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 les événements de lieu de travail qui se chevauchent

Un utilisateur peut avoir plusieurs événements de lieu de travail qui se chevauchent dans son agenda en même temps, ce qui signifie que plusieurs lieux de travail peuvent être définis pour une même heure. Dans les cas où une seule position peut être affichée à l'utilisateur, elle doit être affichée de manière cohérente dans plusieurs applications. Pour ce faire, suivez les consignes ci-dessous pour choisir l'événement à afficher :

  • Les événements programmés sont prioritaires par rapport aux événements d'une journée entière.
  • Les événements uniques sont prioritaires sur les événements récurrents et leurs exceptions.
  • Les événements qui commencent plus tard sont prioritaires sur ceux qui commencent plus tôt.
  • Les événements de courte durée sont prioritaires par rapport à ceux de longue durée.
  • Les événements créés plus récemment prévalent sur ceux créés plus tôt.
  • Les événements qui se chevauchent partiellement doivent être affichés comme 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 de Google Apps Script pour commencer à utiliser Apps Script afin d'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 l'API activée, elle apparaît dans le volet de gauche. Les méthodes et classes disponibles dans l'API peuvent être listées à l'aide du mot clé Calendar 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 que Google Apps Script crée automatiquement. Si vous souhaitez utiliser un projet Google Cloud personnalisé, suivez les étapes ci-dessous pour mettre à jour le projet associé à votre script.

  1. Sur la 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 qui participe au programme Developer Preview, 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 les é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/workspace/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/workspace/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/workspace/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/workspace/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 s'affiche au bas de la fenêtre.