Push-Benachrichtigungen erhalten

In diesem Dokument wird beschrieben, wie Sie Push-Benachrichtigungen verwenden, um Ihre Anwendung über Änderungen an einer Ressource zu informieren.

Übersicht

Die Google Calendar API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an Ressourcen überwachen können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. Sie können die zusätzlichen Netzwerk- und Rechen kosten vermeiden, die beim Abrufen von Ressourcen anfallen, um festzustellen, ob sie sich geändert haben. Wenn sich eine überwachte Ressource ändert, benachrichtigt die Google Calendar API Ihre Anwendung.

Um Push-Benachrichtigungen zu verwenden, müssen Sie zwei Dinge tun:

  • Richten Sie Ihre Empfangs-URL oder den Callback-Empfänger für Webhooks ein.

    Dies ist ein HTTPS-Server, der die API-Benachrichtigungsnachrichten verarbeitet, die ausgelöst werden, wenn sich eine Ressource ändert.

  • Richten Sie für jeden Ressourcenendpunkt, den Sie überwachen möchten , einen Benachrichtigungskanal ein.

    Ein Kanal gibt Routinginformationen für Benachrichtigungs Nachrichten an. Im Rahmen der Kanaleinrichtung müssen Sie die URL angeben, an die Sie Benachrichtigungen senden möchten. Wenn sich die Ressource eines Kanals ändert, sendet die Google Calendar API eine Benachrichtigungsnachricht als eine POST Anfrage an diese URL.

Derzeit unterstützt die Google Calendar API Benachrichtigungen für Änderungen an den ACL, CalendarList, Events und Settings Ressourcen.

Benachrichtigungskanäle erstellen

Wenn Sie Push-Benachrichtigungen anfordern möchten, müssen Sie für jede Ressource, die Sie überwachen möchten, einen Benachrichtigungskanal einrichten. Nachdem Sie Ihre Benachrichtigungskanäle eingerichtet haben , informiert die Google Calendar API Ihre Anwendung, wenn sich eine überwachte Ressource ändert.

Überwachungsanfragen stellen

Jeder überwachbaren Google Calendar API-Ressource ist eine watch Methode mit einem URI im folgenden Format zugeordnet:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Wenn Sie einen Benachrichtigungskanal für Nachrichten über Änderungen an einer bestimmten Ressource einrichten möchten, senden Sie eine POST Anfrage an die watch Methode für die Ressource.

Jeder Benachrichtigungskanal ist sowohl einem bestimmten Nutzer als auch einer bestimmten Ressource (oder einer Reihe von Ressourcen) zugeordnet. Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer Inhaber dieser Ressource ist oder die Berechtigung hat, darauf zuzugreifen.

Beispiel

Überwachung von Änderungen an einer Sammlung von Terminen in einem bestimmten Kalender starten:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

Geben Sie im Anfragetext die id Ihres Kanals, den type als web_hook und Ihre Empfangs-URL in address an. Optional können Sie auch Folgendes angeben:

  • Ein token, das als Kanal-Token verwendet werden soll.
  • Eine expiration-Zeit in Millisekunden für die angeforderte Ablaufzeit des Kanals.

Erforderliche Attribute

Bei jeder watch-Anfrage müssen Sie die folgenden Felder angeben:

  • Ein id Attributstring, der diesen neuen Benachrichtigungskanal in Ihrem Projekt eindeutig identifiziert. Wir empfehlen, eine universell eindeutige ID (UUID) oder einen ähnlichen eindeutigen String zu verwenden. Maximale Länge: 64 Zeichen.

    Der von Ihnen festgelegte ID-Wert wird im X-Goog-Channel-Id HTTP-Header jeder Benachrichtigung Nachricht wiedergegeben, die Sie für diesen Kanal erhalten.

  • Ein type Attributstring, der auf den Wert web_hook festgelegt ist.

  • Ein address-Attributstring, der auf die URL festgelegt ist, die Benachrichtigungen für diesen Benachrichtigungskanal empfängt und darauf reagiert. Dies ist Ihre Webhook-Callback-URL, die HTTPS verwenden muss.

    Die Google Calendar API kann nur dann Benachrichtigungen an diese HTTPS-Adresse senden, wenn auf Ihrem Webserver ein gültiges SSL-Zertifikat installiert ist. Folgende Zertifikate sind nicht gültig:

    • selbst signierte Zertifikate.
    • von einer nicht vertrauenswürdigen Quelle signierte Zertifikate
    • gesperrte Zertifikate.
    • Zertifikate, deren Betreff nicht mit dem Ziel hostname übereinstimmt.

Optionale Attribute

Sie können auch die folgenden optionalen Felder mit Ihrer watch Anfrage angeben:

  • Ein token Attribut, das einen beliebigen Stringwert angibt, der als Kanal-Token verwendet werden soll. Sie können Benachrichtigungskanal Tokens für verschiedene Zwecke verwenden. Sie können das Token beispielsweise verwenden, um zu prüfen, ob jede eingehende Nachricht für einen Kanal bestimmt ist, der von Ihrer Anwendung erstellt wurde. So können Sie sicherstellen, dass die Benachrichtigung nicht gefälscht ist. Außerdem können Sie die Nachricht basierend auf dem Zweck dieses Kanals an das richtige Ziel in Ihrer Anwendung weiterleiten. Maximale Länge: 256 Zeichen.

    Das Token ist im X-Goog-Channel-Token HTTP-Header jeder Benachrichtigungs nachricht enthalten, die Ihre Anwendung für diesen Kanal erhält.

    Wenn Sie Benachrichtigungskanal-Tokens verwenden, empfehlen wir Folgendes:

    • Verwenden Sie ein erweiterbares Codierungsformat wie URL-Abfrage parameter. Beispiel: forwardTo=hr&createdBy=mobile

    • Geben Sie keine vertraulichen Daten wie OAuth-Tokens an.

  • Ein expiration-Attributstring, der auf einen Unix-Zeitstempel (in Millisekunden) des Datums und der Uhrzeit festgelegt ist, zu dem die Google Calendar API keine Nachrichten mehr für diesen Benachrichtigungskanal senden soll.

    Wenn ein Kanal eine Ablaufzeit hat, ist sie als Wert des X-Goog-Channel-Expiration HTTP-Headers (in einem für Menschen lesbaren Format) in jeder Benachrichtigungsnachricht enthalten, die Ihre Anwendung für diesen Kanal erhält.

Weitere Informationen zur Anfrage finden Sie in der API-Referenz unter der watch Methode für die Ressourcen ACL, CalendarList, Events und Settings.

Überwachungsantwort

Wenn mit der watch Anfrage erfolgreich ein Benachrichtigung Kanal erstellt wird, wird der HTTP 200 OK Statuscode zurückgegeben.

Der Inhalt der Nachricht der Überwachungsantwort enthält Informationen zum gerade erstellten Benachrichtigungskanal, wie im folgenden Beispiel zu sehen ist.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

Der Antworttext enthält Details zum Kanal, z. B.:

  • kind: Gibt an, dass es sich um eine API-Kanalressource handelt.
  • id: Die ID, die Sie für diesen Kanal angegeben haben.
  • resourceId: Die ID der überwachten Ressource.
  • resourceUri: Die versionsspezifische ID der überwachten Ressource.
  • token: Das im Anfragetext angegebene Token.
  • expiration: Die Ablaufzeit des Kanals als Unix-Zeitstempel in Millisekunden.

Zusätzlich zu den Attributen, die Sie im Rahmen Ihrer Anfrage gesendet haben, enthalten die zurückgegebenen Informationen auch die resourceId und resourceUri um die Ressource zu identifizieren, die auf diesem Benachrichtigungskanal überwacht wird.

Sie können die zurückgegebenen Informationen an andere Benachrichtigungskanal Vorgänge übergeben, z. B. wenn Sie keine Benachrichtigungen mehr erhalten möchten.

Weitere Informationen zur Antwort finden Sie in der API-Referenz unter der watch Methode für die Ressourcen ACL, CalendarList, Events und Settings.

Synchronisierungsnachricht

Nachdem Sie einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt haben, sendet die Google Calendar API eine sync Nachricht, um anzugeben, dass Benachrichtigungen gesendet werden. Der X-Goog-Resource-State HTTP Headerwert für diese Nachrichten ist sync. Aufgrund von Netzwerk Timing-Problemen kann es vorkommen, dass Sie die sync Nachricht erhalten, bevor Sie die watch Methodenantwort erhalten.

Sie können die sync-Benachrichtigung ignorieren, aber Sie können sie auch verwenden. Wenn Sie beispielsweise den Kanal nicht behalten möchten, können Sie die Werte X-Goog-Channel-ID und X-Goog-Resource-ID in einem Aufruf verwenden, um keine Benachrichtigungen mehr zu erhalten. Sie können die sync Benachrichtigung auch verwenden, um einige Initialisierungen vorzunehmen, um sich auf spätere Ereignisse vorzubereiten.

Das Format von sync Nachrichten, die die Google Calendar API an Ihre Empfangs-URL sendet, ist unten dargestellt.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

`sync`-Nachrichten haben immer den X-Goog-Message-Number HTTP Headerwert von 1. Jede nachfolgende Benachrichtigung für diesen Kanal hat eine Nachrichtennummer, die größer als die vorherige ist. Die Nachrichtennummern sind jedoch nicht fortlaufend.

Benachrichtigungskanäle erneuern

Ein Benachrichtigungskanal kann eine Ablaufzeit haben, deren Wert entweder durch Ihre Anfrage oder durch interne Limits oder Standardwerte der Google Calendar API bestimmt wird (der restriktivere Wert wird verwendet). Die Ablaufzeit des Kanals, falls vorhanden, ist als ein Unix-Zeitstempel (in Millisekunden) in den von der watch Methode zurückgegebenen Informationen enthalten. Außerdem sind das Ablaufdatum und die ‑zeit (in einem für Menschen lesbaren Format) in jeder Benachrichtigungsnachricht enthalten, die Ihre Anwendung für diesen Kanal im X-Goog-Channel-Expiration HTTP-Header erhält.

Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu erneuern. Wenn ein Kanal bald abläuft, müssen Sie ihn durch einen neuen ersetzen, indem Sie die watch Methode aufrufen. Wie immer müssen Sie für das id Attribut des neuen Kanals einen eindeutigen Wert verwenden. Es ist wahrscheinlich, dass es einen Zeitraum gibt, in dem die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.

Benachrichtigungen erhalten

Wenn sich eine überwachte Ressource ändert, erhält Ihre Anwendung eine Benachrichtigungsnachricht, in der die Änderung beschrieben wird. Die Google Calendar API sendet diese Nachrichten als HTTPS-POST Anfragen an die URL, die Sie als das address Attribut für diesen Benachrichtigungskanal angegeben haben.

Format der Benachrichtigungsnachricht interpretieren

Alle Benachrichtigungsnachrichten enthalten eine Reihe von HTTP-Headern mit X-Goog- Präfixen. Einige Arten von Benachrichtigungen können auch einen Nachrichtentext enthalten.

Header

Benachrichtigungsnachrichten, die von der Google Calendar API an Ihre Empfangs- URL gesendet werden, enthalten die folgenden HTTP-Header:

Header Beschreibung
Immer vorhanden
X-Goog-Channel-ID UUID oder anderer eindeutiger String, den Sie zur Identifizierung dieses Benachrichtigungskanals angegeben haben.
X-Goog-Message-Number Ganzzahl, die diese Nachricht für diesen Benachrichtigungskanal identifiziert. Der Wert ist für sync-Nachrichten immer 1. Die Nachrichtennummern werden für jede nachfolgende Nachricht im Kanal erhöht, sind aber nicht fortlaufend.
X-Goog-Resource-ID Ein intransparenter Wert, der die überwachte Ressource identifiziert. Diese ID ist über API-Versionen hinweg stabil.
X-Goog-Resource-State Der neue Ressourcenstatus, der die Benachrichtigung ausgelöst hat. Mögliche Werte: sync, exists, oder not_exists.
X-Goog-Resource-URI Eine API-versionsspezifische ID für die überwachte Ressource.
Manchmal vorhanden
X-Goog-Channel-Expiration Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in einem für Menschen lesbaren Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Benachrichtigungskanal-Token, das von Ihrer Anwendung festgelegt wurde und mit dem Sie die Benachrichtigungsquelle überprüfen können. Nur vorhanden, wenn definiert.

Benachrichtigungsnachrichten, die von der Calendar API an Ihre Empfangs-URL gesendet werden, enthalten keinen Nachrichtentext. Diese Nachrichten enthalten keine spezifischen Informationen zu aktualisierten Ressourcen. Sie müssen einen weiteren API-Aufruf ausführen, um alle Details zu Änderungen zu sehen.

Beispiel

Benachrichtigungsnachricht für eine geänderte Sammlung von Terminen:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

Auf Benachrichtigungen reagieren

Um den Erfolg anzugeben, können Sie einen der folgenden Statuscodes zurückgeben: 200, 201, 202, 204, oder 102.

Wenn Ihr Dienst die API-Clientbibliothek von Google verwendet und 500,502, 503, oder 504 zurückgibt, wiederholt die Google Calendar API den Vorgang mit exponentiellem Backoff. Jeder andere zurückgegebene Statuscode wird als Nachrichtenfehler betrachtet.

Benachrichtigungsereignisse der Google Calendar API

In diesem Abschnitt finden Sie Details zu den Benachrichtigungsnachrichten, die Sie erhalten können, wenn Sie Push-Benachrichtigungen mit der Google Calendar API verwenden.

X-Goog-Resource-State Gilt für Wird gesendet, wenn
sync ACLs, Kalenderlisten, Termine, Einstellungen. Ein neuer Kanal wurde erstellt. Benachrichtigungen können jetzt empfangen werden.
exists ACLs, Kalenderlisten, Termine, Einstellungen. Eine Ressource wurde geändert. Mögliche Änderungen sind das Erstellen einer neuen Ressource oder das Ändern oder Löschen einer vorhandenen Ressource.

Benachrichtigungen deaktivieren

Das Attribut expiration steuert, wann die Benachrichtigungen automatisch beendet werden. Sie können Benachrichtigungen für einen bestimmten Kanal beenden, bevor er abläuft, indem Sie die stop-Methode mit dem folgenden URI aufrufen:

https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop

Für diese Methode müssen Sie mindestens die Attribute des Kanals id und die resourceId angeben, wie im folgenden Beispiel zu sehen ist. Beachten Sie, dass, wenn die Google Calendar API mehrere Ressourcentypen mit Ressourcen hat, die watch Methoden haben, es nur eine stop Methode gibt.

Nur Nutzer mit der entsprechenden Berechtigung können einen Kanal beenden. Insbesondere gilt:

  • Wenn der Kanal von einem regulären Nutzerkonto erstellt wurde, kann nur derselbe Nutzer vom selben Client (identifiziert durch die OAuth 2.0-Client-IDs aus den Autorisierungstokens), der den Kanal erstellt hat, den Kanal beenden.
  • Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer vom selben Client den Kanal beenden.

Das folgende Codebeispiel zeigt, wie Sie keine Benachrichtigungen mehr erhalten:

POST https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}