Erweiterte Properties

Die Felder der Ereignisressourcen decken die gängigsten Daten im Zusammenhang mit einem Ereignis ab, z. B. Ort und Startzeit. Unter Umständen möchten Anwendungen jedoch zusätzliche Metadaten für ihren Anwendungsfall speichern. Die Calendar API bietet die Möglichkeit, ausgeblendete Schlüssel/Wert-Paare mit einem Ereignis festzulegen, das als erweiterte Attribute bezeichnet wird. Erweiterte Attribute machen es einfach, anwendungsspezifische Daten für ein Ereignis zu speichern, ohne eine externe Datenbank verwenden zu müssen.

Sichtbarkeit

Es gibt zwei Arten von erweiterten Properties: private und gemeinsam genutzte Properties. Gemeinsame Properties sind für alle Teilnehmer eines Termins sichtbar und bearbeitbar, während private Properties auf der lokalen Kopie des Termins für einen Teilnehmer festgelegt werden. Konkreter sind private Properties spezifisch für die in der Anfrage verwendeten calendarId und eventId. Gemeinsame Properties werden hingegen unabhängig vom in der Anfrage verwendeten calendarId angezeigt.

Properties hinzufügen und aktualisieren

Erweiterte Attribute werden für die Ereignisressource festgelegt und wie andere Felder können in Anfragen vom Typ insert, update und patch festgelegt werden. Patchanfragen sind die bevorzugte Methode, da Sie damit einige Eigenschaften ändern können, während andere unberührt bleiben. Wenn Sie ein neues Attribut mit demselben Schlüssel hinzufügen, werden alle vorhandenen Attribute mit demselben Schlüssel überschrieben. Das folgende Beispiel zeigt, wie Sie eine private Property festlegen:

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

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

Unterkünfte löschen

Alle Attribute, die nicht in einer Aktualisierungsanfrage enthalten sind, werden gelöscht. Es empfiehlt sich jedoch, eine Patchanfrage zu senden, um den Wert auf null zu setzen. Das folgende Beispiel zeigt, wie ein Privatgrundstück gelöscht wird:

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 Attribute suchen. Legen Sie für das Feld privateExtendedProperty oder sharedExtendedProperty eine Einschränkung im Format propertyName=value fest, mit der nach privaten bzw. gemeinsam genutzten Properties gesucht wird. 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 und die Einschränkungen werden mit ODER verknüpft. Ereignisse müssen also nur mit einer der Einschränkungen übereinstimmen, um zurückgegeben zu werden. Im folgenden Beispiel werden Ereignisse mit dem Privatgrundstück 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 gemeinsam genutzte Properties jedoch durch UND verknüpft sind. Ereignisse müssen also mit beiden Gruppen von Einschränkungen übereinstimmen, um zurückgegeben zu werden. Im folgenden Beispiel werden Veranstaltungen mit den privaten Attributen 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

Einschränkungen

1. Die maximale Größe eines Schlüssels eines Attributs beträgt 44 Zeichen. Attribute mit längeren Schlüsseln werden ohne Meldung entfernt.
2. Die maximale Größe eines Attributwerts beträgt 1.024 Zeichen. Attribute mit längeren Werten werden automatisch abgeschnitten.
3. Ein Ereignis kann bis zu 300 Attribute mit einer Größe von insgesamt bis zu 32 KB haben (Schlüsselgröße + Wertgröße). Diese 300 Properties umfassen gemeinsame und private Properties für alle „Kopien“ des Ereignisses.