Propriétés étendues

Les champs des ressources "Events" (Événements) 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 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 de l'événement par un participant. 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 sont affichées quelle que soit la calendarId utilisée 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, vous pouvez les définir dans les requêtes insert, update et patch. L'utilisation de requêtes patch est la méthode privilégiée, car elle vous permet de manipuler certaines propriétés tout en laissant d'autres intactes. Si vous ajoutez une propriété avec la même clé, toutes les propriétés existantes possédant la même clé seront écrasées. 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 non incluses dans une requête de mise à jour seront supprimées, mais il est préférable d'envoyer une requête patch 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 établissements

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 les propriétés privées et partagées respectivement. 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 liées par l'opérateur OU. Ainsi, les événements ne doivent correspondre qu'à l'une des contraintes pour être renvoyés. L'exemple suivant trouve des événements associés à 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 liées par l'opérateur ET. Par conséquent, les événements doivent correspondre aux deux ensembles de contraintes pour être renvoyés. L'exemple suivant trouve des é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 ayant des clés 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 ayant des valeurs plus longues sont tronquées sans notification.
3. Un événement peut comporter jusqu'à 300 propriétés, d'une taille maximale de 32 Ko (taille des clés + taille de la valeur). Ces 300 propriétés incluent des propriétés partagées et privées, sur toutes les "copies" de l'événement.