Propriétés étendues

Les champs des ressources Events couvrent les données les plus courantes associées à un événement, telles que le lieu, l'heure de début, etc. Toutefois, les applications peuvent souhaiter stocker des métadonnées supplémentaires spécifiques à leur cas d'utilisation. L'API Calendar permet de définir des paires clé-valeur masquées avec un événement, appelées propriétés étendues. Les propriétés étendues facilitent le stockage des données spécifiques à l'application pour un événement sans avoir à utiliser de base de données externe.

Visibilité

Il existe deux types de propriétés étendues : privées et partagées. Les propriétés partagées sont visibles et modifiables par tous les participants à un événement, tandis que les propriétés privées sont définies sur la "copie" locale de l'événement d'un participant. Plus concrètement, les propriétés privées sont spécifiques aux calendarId et eventId utilisés dans la requête, tandis que les propriétés partagées s'affichent quel que soit le calendarId utilisé dans la requête.

Ajouter et mettre à jour des propriétés

Les propriétés étendues sont définies sur la ressource Events et, comme d'autres champs, peuvent être définies dans les requêtes d'insertion, mise à jour et de correction. L'utilisation de requêtes de correction est la méthode privilégiée, car elle vous permet de manipuler certaines propriétés tout en laissant les autres intactes. L'ajout d'une nouvelle propriété avec la même clé écrase toutes les propriétés existantes avec la même clé. L'exemple suivant montre comment définir une propriété privée :

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

Supprimer des propriétés

Toutes les propriétés qui ne sont pas incluses dans une requête de mise à jour sont supprimées, mais une meilleure approche consiste à effectuer une requête de correction pour définir la valeur sur "null". L'exemple suivant montre comment supprimer une propriété privée :

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

Rechercher des propriétés

Vous pouvez rechercher des événements en fonction des valeurs de leurs propriétés étendues à l'aide d'une requête Events.list. Définissez le champ privateExtendedProperty ou sharedExtendedProperty sur une contrainte au format propertyName=value, qui effectue respectivement une recherche sur les propriétés privées et partagées. L'exemple suivant renvoie les événements avec la propriété privée petsAllowed=yes :

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes

Vous pouvez répéter ces champs plusieurs fois. Les contraintes sont combinées avec l'opérateur OR. Par conséquent, les événements n'ont besoin de correspondre qu'à l'une des contraintes pour être renvoyés. L'exemple suivant recherche les événements avec la propriété privée petsAllowed=yes ou isOutside=yes :

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &privateExtendedProperty=isOutside%3Dyes

Sachez toutefois que les contraintes sur les propriétés privées et partagées sont combinées avec l'opérateur AND. Par conséquent, les événements doivent correspondre aux deux ensembles de contraintes pour être renvoyés. L'exemple suivant recherche les événements avec la propriété privée petsAllowed=yes et la propriété publique createdBy=myApp :

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &sharedExtendedProperty=createdBy%3DmyApp

Limites

1. La taille maximale de la clé d'une propriété est de 44 caractères. Les propriétés dont les clés sont plus longues sont supprimées sans notification.
2. La taille maximale de la valeur d'une propriété est de 1 024 caractères. Les propriétés dont les valeurs sont plus longues sont tronquées sans notification.
3. Un événement peut comporter jusqu'à 300 propriétés, pour une taille totale maximale de 32 Ko (taille des clés + taille des valeurs). Ces 300 propriétés incluent les propriétés partagées et privées, dans toutes les "copies" de l'événement.