Erweiterte Properties

Die Felder der Ereignisressourcen umfassen die gängigsten Daten, die mit einem Ereignis verknüpft sind, z. B. Ort und Beginnzeit. In Anwendungen können jedoch zusätzliche Metadaten gespeichert werden, die für den jeweiligen Anwendungsfall spezifisch sind. Mit der Kalender API können Sie für ein Ereignis ausgeblendete Schlüssel/Wert-Paare festlegen, die als erweiterte Eigenschaften bezeichnet werden. Mit erweiterten Properties können Sie anwendungsspezifische Daten für ein Ereignis ganz einfach speichern, ohne eine externe Datenbank verwenden zu müssen.

Sichtbarkeit

Es gibt zwei Arten von erweiterten Properties: privat und gemeinsam genutzt. Freigegebene Properties sind für alle Teilnehmer einer Veranstaltung sichtbar und bearbeitbar. Private Properties werden in der lokalen Kopie der Veranstaltung eines Teilnehmers festgelegt. Private Properties sind spezifisch für die in der Anfrage verwendeten calendarId und eventId, während freigegebene Properties unabhängig von der in der Anfrage verwendeten calendarId angezeigt werden.

Unterkünfte hinzufügen und aktualisieren

Erweiterte Properties werden für die „Ereignisse“-Ressource festgelegt und können wie andere Felder in insert-, update- und patch-Anfragen festgelegt werden. Die Verwendung von Patchanfragen ist die bevorzugte Methode, da Sie damit einige Properties ändern und andere unverändert lassen können. 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 Property festgelegt:

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

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

Properties löschen

Alle Properties, die nicht in einer Aktualisierungsanfrage enthalten sind, werden gelöscht. Besser ist es jedoch, eine Patch-Anfrage zu senden, um den Wert auf „null“ zu setzen. Im folgenden Beispiel wird das Löschen einer privaten Property veranschaulicht:

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

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

Eigenschaften suchen

Mit einer Events.list-Anfrage können Sie nach Ereignissen suchen, die anhand der Werte ihrer erweiterten Properties gefiltert werden. Legen Sie für das Feld privateExtendedProperty oder sharedExtendedProperty eine Einschränkung im Format propertyName=value fest, um jeweils nach privaten und freigegebenen Unterkünften zu suchen. Im folgenden Beispiel werden Ereignisse mit der privaten Property 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 OR verknüpft. Ereignisse müssen also nur einer der Einschränkungen entsprechen, um zurückgegeben zu werden. Im folgenden Beispiel werden Ereignisse mit der privaten Property petsAllowed=yes oder isOutside=yes ermittelt:

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 jedoch mit „AND“ verknüpft sind. Ereignisse müssen also beiden Einschränkungen entsprechen, um zurückgegeben zu werden. Im folgenden Beispiel werden Ereignisse mit der privaten Property petsAllowed=yes und der öffentlichen Property createdBy=myApp ermittelt:

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

Limits

1. Der Schlüssel einer Property darf maximal 44 Zeichen lang sein. Properties mit längeren Schlüsseln werden ohne Benachrichtigung gelöscht.
2. Der Wert einer Property darf maximal 1.024 Zeichen lang sein. Bei Properties mit längeren Werten erfolgt ein geräuschloses Kürzen.
3. Ein Ereignis kann bis zu 300 Eigenschaften mit einer Gesamtgröße von bis zu 32 KB haben (Schlüsselgröße + Wertgröße). Diese 300 Unterkünfte umfassen freigegebene und private Unterkünfte in allen „Kopien“ der Veranstaltung.