Erweiterte Properties

Die Felder der Events-Ressourcen enthalten die häufigsten Daten im Zusammenhang mit einem Ereignis, 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 die Möglichkeit nutzen, verborgene Schlüssel/Wert-Paare mit einem Ereignis festzulegen, sogenannte erweiterte Properties. Mit erweiterten Properties 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 Properties: private und shared. Freigegebene Properties sind für alle Teilnehmer eines Ereignisses sichtbar und bearbeitbar, während private Properties in der lokalen „Kopie“ des Ereignisses eines Teilnehmers festgelegt werden. Genauer gesagt sind private Properties spezifisch für die calendarId und eventId, die in der Anfrage verwendet werden. Freigegebene Properties werden unabhängig von der in der Anfrage verwendeten calendarId angezeigt.

Properties hinzufügen und aktualisieren

Erweiterte Properties werden für die Events-Ressource festgelegt und können wie andere Felder in insert, update und patch-Anfragen festgelegt werden. Patch-Anfragen sind 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 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 Update-Anfrage enthalten sind, werden gelöscht. Ein besserer Ansatz ist jedoch, 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
    }
  }
}

Properties suchen

Mit einer Events.list-Anfrage können Sie Ereignisse anhand der Werte ihrer erweiterten Properties suchen. Setzen Sie das Feld privateExtendedProperty oder sharedExtendedProperty auf eine Einschränkung im Format propertyName=value, wodurch jeweils private und freigegebene Properties durchsucht werden. 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 gesucht:

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

Einschränkungen für private und freigegebene Properties werden jedoch mit AND verknüpft. Ereignisse müssen also beiden Einschränkungssätzen entsprechen, um zurückgegeben zu 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 Property beträgt 44 Zeichen. Properties mit längeren Schlüsseln werden ohne Benachrichtigung gelöscht.
2. Die maximale Größe des Werts einer Property beträgt 1.024 Zeichen. Properties mit längeren Werten werden ohne Benachrichtigung abgeschnitten.
3. Ein Ereignis kann bis zu 300 Properties mit einer Gesamtgröße von bis zu 32 KB haben (Schlüsselgröße + Wertgröße). Diese 300 Properties umfassen freigegebene und private Properties in allen „Kopien“ des Ereignisses.