Propriétés étendues

Les champs des ressources d'é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 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 modifier des établissements

Les propriétés étendues sont définies sur la ressource "Events" et, comme les autres champs, peuvent être définies dans les requêtes insert, update et patch. L'utilisation de requêtes PATCH est la méthode recommandée, car elle vous permet de manipuler certaines propriétés tout en laissant les autres intactes. Si vous ajoutez une propriété avec la même clé, elle écrasera 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 non incluses dans une requête de mise à jour seront supprimées. Toutefois, 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 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 des recherches respectivement sur les propriétés privées et partagées. L'exemple suivant renvoie les événements dont la propriété privée est 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 un opérateur OR. Les événements n'ont donc 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

Notez que les contraintes sur les propriétés privées et partagées sont combinées avec un 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 seront 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 seront tronquées sans notification.
3. Un événement peut comporter jusqu'à 300 propriétés, pour une taille totale 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, pour toutes les "copies" de l'événement.