Propriétés étendues

Les champs des ressources Events couvrent les données les plus courantes associées à un événement, telles que l'emplacement, l'heure de début, etc., mais les applications peuvent souhaiter stocker des métadonnées supplémentaires spécifiques à leur cas d'utilisation. L'API Agenda 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 permettent de stocker facilement des données spécifiques à une application pour un événement sans avoir à utiliser une 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 d'un participant à l'événement. Plus précisément, 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 établissements

Les propriétés étendues sont définies sur la ressource "Événements". Comme les autres champs, elles peuvent être définies dans les requêtes insert, update et patch. La méthode privilégiée consiste à utiliser des requêtes de correction, car elle vous permet de manipuler certaines propriétés tout en laissant d'autres intactes. L'ajout d'une propriété avec la même clé écrase toutes les propriétés existantes ayant 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 seront supprimées. Toutefois, il est préférable d'envoyer 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
    }
  }
}

Sites de recherche

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 recherche respectivement des propriétés privées et partagées. L'exemple suivant renvoie des é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, et les contraintes sont associées à l'opérateur OR. Par conséquent, les événements ne doivent correspondre qu'à l'une des contraintes pour être renvoyés. L'exemple suivant recherche des é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

Notez toutefois que les contraintes sur les propriétés privées et partagées sont associées à 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 la clé est plus longue 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 la valeur est plus longue sont tronquées sans notification.
3. Un événement peut comporter jusqu'à 300 propriétés, dont la taille totale ne doit pas dépasser 32 ko (taille des clés + taille des valeurs). Ces 300 propriétés incluent des propriétés partagées et privées, pour toutes les "copies" de l'événement.