Erweiterte Properties

Die Felder der Events-Ressourcen decken die meisten gängigen Daten ab, die mit einem Ereignis verknüpft sind, z. B. Ort und Startzeit. Anwendungen möchten jedoch möglicherweise zusätzliche Metadaten speichern, die für ihren Anwendungsfall spezifisch sind. Mit der Calendar API können Sie verborgene Schlüssel/Wert-Paare für ein Ereignis festlegen. Diese werden als erweiterte Eigenschaften bezeichnet. Mit erweiterten Eigenschaften lassen sich anwendungsspezifische Daten für ein Ereignis ganz einfach speichern, ohne dass eine externe Datenbank erforderlich ist.

Sichtbarkeit

Es gibt zwei Arten von erweiterten Eigenschaften: private und freigegebene. Freigegebene Attribute sind für alle Teilnehmer einer Veranstaltung sichtbar und bearbeitbar, während private Attribute in der lokalen „Kopie“ der Veranstaltung eines Teilnehmers festgelegt werden. Genauer gesagt sind private Properties spezifisch für die calendarId und eventId, die in der Anfrage verwendet werden, während freigegebene Properties unabhängig von der in der Anfrage verwendeten calendarId angezeigt werden.

Unterkünfte hinzufügen und aktualisieren

Erweiterte Eigenschaften werden für die Events-Ressource festgelegt und können wie andere Felder in insert-, update- und patch-Anfragen festgelegt werden. Die Verwendung von Patch-Anfragen ist die bevorzugte Methode, da Sie damit einige Properties bearbeiten können, während andere unverändert bleiben. Wenn Sie eine neue Property mit demselben Schlüssel hinzufügen, werden alle vorhandenen Properties mit demselben Schlüssel überschrieben. Im folgenden Beispiel wird eine private Eigenschaft festgelegt:

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

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

Properties löschen

Alle Attribute, die nicht in einer Aktualisierungsanfrage enthalten sind, werden gelöscht. Es ist jedoch besser, eine Patch-Anfrage zu senden, um den Wert auf „null“ zu setzen. Im folgenden Beispiel wird eine private Property gelöscht:

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

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

Eigenschaften suchen

Sie können Ereignisse anhand der Werte ihrer erweiterten Eigenschaften mit einer Events.list-Anfrage suchen. Legen Sie für das Feld privateExtendedProperty oder sharedExtendedProperty eine Einschränkung im Format propertyName=value fest, um jeweils nach privaten und freigegebenen Attributen zu suchen. Im folgenden Beispiel werden Ereignisse mit dem privaten Attribut petsAllowed=yes zurückgegeben:

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

Sie können diese Felder mehrmals wiederholen. Die Einschränkungen werden mit ODER verknüpft. Ereignisse müssen also nur einer der Einschränkungen entsprechen, damit sie zurückgegeben werden. Im folgenden Beispiel werden Ereignisse mit der privaten Property petsAllowed=yes oder isOutside=yes gesucht:

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

Beachten Sie, dass Einschränkungen für private und freigegebene Properties mit AND verknüpft werden. Ereignisse müssen also beiden Einschränkungssätzen entsprechen, damit sie zurückgegeben werden. Im folgenden Beispiel werden Ereignisse mit der privaten Property petsAllowed=yes und der öffentlichen Property createdBy=myApp gesucht:

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

Limits

1. Die maximale Größe des Schlüssels einer Eigenschaft beträgt 44 Zeichen. Eigenschaften mit längeren Schlüsseln werden ohne Benachrichtigung verworfen.
2. Die maximale Größe des Werts einer Eigenschaft beträgt 1.024 Zeichen. Eigenschaften mit längeren Werten werden ohne Benachrichtigung abgeschnitten.
3. Ein Ereignis kann bis zu 300 Eigenschaften mit einer Gesamtgröße von bis zu 32 KB (Schlüsselgröße + Wertgröße) haben. Diese 300 Eigenschaften umfassen freigegebene und private Eigenschaften für alle „Kopien“ des Ereignisses.