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

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 qui affichent le statut des utilisateurs de Google Agenda. Les événements d'état décrivent où se trouvent les utilisateurs ce qu'ils sont en train de faire, par exemple en ce qui concerne les moments de concentration, les absences du bureau travaillant depuis un certain endroit.

Dans Google Agenda, les utilisateurs peuvent définir des moments de concentration, des absences du bureau et des heures de travail. de localisation pour indiquer leur état et leur emplacement personnalisés. Ces fonctionnalités sont n'est disponible 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 utilisateurs.

Consulter et répertorier les événements de disponibilité dans Agenda

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

Pour lire un événement de statut, utilisez la events.get, en spécifiant la 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 Champ eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

Ensuite, dans les objets Event renvoyés, vérifiez que le Le champ eventType contient la valeur demandée et reportez-vous au champ correspondant pour en savoir plus é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 le Ressource Events du API Calendar

Utilisez le events.watch, en spécifiant la calendarId sur Agenda auquel vous abonner et une ou plusieurs des valeurs suivantes dans la section Champ eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

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

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

Si vous mettez à jour l'événement de statut avec events.update, l'événement doit remplir les champs obligatoires.

Créer un moment de concentration

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

Définir eventType sur 'focusTime'
Incluez les focusTimeProperties .
Définissez la transparency sur 'opaque'.
Définissez les start de l'événement et Les champs end doivent être un événement programmé. (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 entière.

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 "Absent du bureau" :

Définir eventType sur 'outOfOffice'
Incluez les outOfOfficeProperties .
Définissez la transparency sur 'opaque'.
Définissez les start de l'événement et Les champs end doivent être un événement programmé. (avec les 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 Afficher quand vous êtes bureau

Créer un lieu de travail

Pour créer un événement lié à votre lieu de travail:

Définir eventType sur 'workingLocation'
Incluez les workingLocationProperties .
Définir le champ visibility à 'public'.
Définissez la transparency sur 'transparent'.
Définissez les start de l'événement et Les champs end doivent être soit:
- Un événement programmé (avec les 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) qui s'étend sur exactement un jour.
Les événements de type "Lieu de travail d'une journée" ne peuvent pas s'étendre sur plusieurs jours, mais des événements planifiés que possible.

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

workingLocationProperties.officeLocation.buildingId: Elle doit correspondre à un buildingId de l'organisation ressources base de données. Les utilisateurs bénéficient ainsi de toutes les fonctionnalités d'Agenda, par exemple suggestions de salles.
workingLocationProperties.officeLocation.label: Il s'agit du libellé qui s'affiche dans les clients Web et mobile Agenda. Toi vous pouvez récupérer les identifiants et les libellés des bâtiments à l'aide de la resources.buildings.list .

Créer et mettre à jour des événements de lieu de travail via des points de terminaison par lot compatibles.

Pour en savoir plus sur cette fonctionnalité, consultez l'article Définir vos heures de travail et vos emplacement et activer ou désactiver le lieu de travail pour utilisateurs

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

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 horaire donné peut avoir plusieurs heures ou les emplacements qui lui sont associés. Dans les cas où un seul établissement peut être affiché auprès de l'utilisateur, cette position doit lui être présentée de manière cohérente sur applications. Pour ce faire, suivez les consignes ci-dessous événement à afficher:

Les événements planifiés prennent sur les événements d'une journée entière.
Les événements uniques sont prioritaires sur les événements périodiques et leurs exceptions.
Les événements démarrant plus tard prévalent sur ceux qui commencent plus tôt.
Les événements dont la durée est plus courte sont prioritaires sur ceux dont la durée est plus longue et différentes durées.
Les événements créés plus récemment sont prioritaires sur ceux qui ont été créés. plus tôt.
Les événements qui se chevauchent partiellement doivent être affichés sous la forme de deux événements différents chacun avec leur propre lieu de travail.

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

Google Apps Script est un service cloud basé sur JavaScript qui permet de créer des applications d'entreprise qui s'intègrent Google Workspace. Les scripts sont développés dans un éditeur de code intégré au navigateur. elles sont stockées et exécutées sur les serveurs de Google. Voir aussi Google Apps Script de démarrage rapide 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 la classe l'API Google Calendar en tant que service avancé dans Google Apps Script. Pour obtenir la liste complète des ressources et méthodes de l'API Google Agenda, consultez la documentation de référence.

Créer et configurer le script

Créez un script en accédant à script.google.com/create.
Dans le volet de gauche à côté de Services, cliquez sur "Ajouter un service".
Sélectionnez API Google Calendar, puis cliquez sur Ajouter.
Une fois l'API activée, elle apparaît dans le volet de gauche. Les méthodes et de 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 peut utiliser le projet par défaut que Google Apps Script s'occupe automatiquement crée. Si vous souhaitez utiliser un projet Google Cloud personnalisé, procédez comme suit : pour mettre à jour le projet associé à votre script.

Dans la partie gauche de l'éditeur, cliquez sur "Project Settings" (Paramètres du projet).
Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.
Saisissez le numéro du projet Google Cloud qui se trouve dans la ressource Programme Preview, puis cliquez sur Définir le projet.
Sur la gauche, sélectionnez Éditeur pour revenez à 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.

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

primary est un mot clé permettant d'accéder à l'instance principale l'agenda de l'utilisateur connecté. Pour récupérer les événements d'un autre agenda, définissez le paramètre calendarId sur une adresse e-mail. Cela vous permet consulter les événements de statut dans les agendas d'autres utilisateurs au minimum l'accès aux données de disponibilité. Les agendas secondaires ne peuvent pas comporter d'événements de statut.

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

Au-dessus de l'éditeur de code, sélectionnez la fonction à exécuter dans le menu déroulant, puis cliquez sur Exécuter.
Lors de la première exécution, vous êtes invité à autoriser l'accès. Examiner et autoriser Apps Script pour accéder à votre agenda.
Vous pouvez inspecter les résultats de l'exécution du script dans la Execution Log (Journal d'exécution) qui s'affiche en bas de la fenêtre.