Push-Benachrichtigungen

In diesem Dokument wird beschrieben, wie Sie Push-Benachrichtigungen verwenden, um Ihre wenn sich eine Ressource ändert.

Übersicht

Die Google Calendar API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an den Ressourcen. Mit dieser Funktion können Sie die Leistung Ihrer Ihre Anwendung. Sie eliminieren zusätzliche Netzwerk- und Rechenleistung Kosten für das Abfragen von Ressourcen, um festzustellen, ob sie sich geändert haben. Wenn sich eine beobachtete Ressource ändert, benachrichtigt die Google Calendar API Ihr .

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

  • Empfangs-URL oder Webhook einrichten des Rückrufempfängers.

    Dieses ist ein HTTPS-Server, der API-Benachrichtigungen verarbeitet, die wird ausgelöst, wenn sich eine Ressource ändert.

  • Richten Sie einen (Benachrichtigungskanal) für jeden Ressourcenendpunkt ein, den Sie einrichten möchten. ansehen.

    Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Nachrichten. Bei der Einrichtung des Channels müssen Sie die URL angeben, unter der Sie Benachrichtigungen erhalten möchten. Wenn sich die Ressourcen eines Kanals ändern, Die Google Calendar API sendet eine Benachrichtigung als POST an diese URL senden.

Derzeit unterstützt die Google Calendar API Benachrichtigungen über Änderungen an Ressourcen Acl, CalendarList, Events und Settings

Benachrichtigungskanäle erstellen

Um Push-Benachrichtigungen anzufordern, musst du einen Benachrichtigungskanal einrichten für jede Ressource, die Sie überwachen möchten. Nach dem Festlegen der Benachrichtigungskanäle informiert die Google Calendar API Ihre Anwendung, sobald eine beobachtete Ressource Änderungen.

Wiedergabeanfragen stellen

Jeder Watchable Google Calendar API-Ressource ist ein watch bei einem URI der folgenden Form:

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

So richten Sie einen Benachrichtigungskanal für Benachrichtigungen über Änderungen an einer bestimmten Ressource, senden Sie eine POST-Anfrage an den Die Methode watch für die Ressource.

Jeder Benachrichtigungskanal ist sowohl einem bestimmten Nutzer als auch eine bestimmte Ressource (oder eine Gruppe von Ressourcen) Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer besitzt oder hat die Berechtigung, auf diese Ressource zuzugreifen.

Beispiel

Suchen Sie nach Änderungen an einer Terminsammlung in einem bestimmten Kalender:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

Erforderliche Properties

Bei jeder watch-Anfrage müssen die folgenden Felder angegeben werden:

  • Ein id-Attributstring, der dieses Objekt eindeutig identifiziert in Ihrem Projekt zu erstellen. Wir empfehlen die Verwendung von eine universell eindeutige Kennung (UUID) oder Ähnliches eindeutigen String hinzu. Maximale Länge: 64 Zeichen.

    Der von Ihnen festgelegte ID-Wert wird im X-Goog-Channel-Id-HTTP-Header jeder Benachrichtigung die du für diesen Kanal erhältst.

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

  • Einen address-Property-String, der auf die URL festgelegt ist, die überwacht und reagiert auf Benachrichtigungen für diesen Benachrichtigungskanal. Dies ist Ihre Webhook-Callback-URL und muss HTTPS verwenden.

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

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

Optionale Attribute

Sie können diese optionalen Felder auch mit Ihrem watch-Anfrage:

  • Ein token-Attribut, das einen beliebigen String angibt. -Wert zur Verwendung als Kanaltoken. Du kannst den Benachrichtigungskanal verwenden für verschiedene Zwecke. Sie können beispielsweise die Methode um zu überprüfen, ob alle eingehenden Nachrichten zu einem Kanal gehören, Anwendung erstellt, um sicherzustellen, dass die Benachrichtigung nicht um Spoofing zu verhindern, oder die Nachricht an das richtige Ziel innerhalb entsprechend dem Zweck dieses Kanals anpassen. Maximale Länge: 256 Zeichen.

    Das Token ist im X-Goog-Channel-Token-HTTP-Header in jeder Benachrichtigung Nachricht, die deine Anwendung für diesen Kanal erhält.

    Wenn Sie Tokens für Benachrichtigungskanäle verwenden, empfehlen wir Folgendes:

    • Verwenden Sie ein erweiterbares Codierungsformat, z. B. URL-Suchanfrage. Parameter. Beispiel: forwardTo=hr&createdBy=mobile

    • Verwenden Sie keine sensiblen Daten wie OAuth-Tokens.

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

    Wenn ein Channel eine Ablaufzeit hat, wird dieser als Wert des HTTP-Headers X-Goog-Channel-Expiration (für Menschen lesbar) Format) in jeder Benachrichtigung, die Ihr Anwendung für diesen Kanal erhält.

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

Antwort ansehen

Wenn die watch-Anfrage erfolgreich eine Benachrichtigung erstellt wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Überwachungsantwort enthält Informationen über die den Sie gerade erstellt haben, wie im folgenden Beispiel gezeigt.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

Zusätzlich zu den Eigenschaften, die Sie im Rahmen Ihrer Anfrage gesendet haben, enthält der die zurückgegebenen Informationen auch die resourceId und resourceUri, um die dafür zu überwachende Ressource zu identifizieren Benachrichtigungskanal.

Sie können die zurückgegebenen Informationen an einen anderen Benachrichtigungskanal weitergeben. z. B. wenn Sie den Erhalt von E-Mails nicht mehr Benachrichtigungen.

Weitere Informationen zur Antwort findest du in den watch. für die Ressourcen Acl, CalendarList, Events und Settings in der API-Referenz.

Nachricht synchronisieren

Nachdem Sie einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt haben, zeigt der Die Google Calendar API sendet eine sync-Nachricht, um anzugeben, dass Benachrichtigungen werden gestartet. Das X-Goog-Resource-State-HTTP Der Headerwert für diese Nachrichten ist sync. Aufgrund des Netzwerks Probleme mit dem Zeitplan haben, ist es möglich, dass die sync-Nachricht noch bevor Sie die Antwort der Methode watch erhalten.

Du kannst die sync-Benachrichtigung ignorieren, aber du kannst verwenden. Wenn Sie z. B. entscheiden, Ihre des Kanals, können Sie X-Goog-Channel-ID und X-Goog-Resource-ID-Werte in einem Aufruf von keine Benachrichtigungen mehr erhalten. Sie können auch die sync-Benachrichtigung an, eine Initialisierung durchzuführen, um sich auf späteren Terminen.

Das Format der sync-Nachrichten, an die die Google Calendar API sendet Ihre Empfangs-URL wird unten angezeigt.

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

Synchronisierungsnachrichten haben immer das HTTP-Statuscode X-Goog-Message-Number Headerwert von 1. Jede weitere Benachrichtigung für diesen Kanal hat die größer als die vorherige ist, auch wenn die Meldung keine fortlaufende Nummerierung.

Benachrichtigungskanäle verlängern

Ein Benachrichtigungskanal kann eine Ablaufzeit haben, mit einem Wert der entweder durch Ihre Anfrage oder durch interne Beschränkungen der Google Calendar API bestimmt wird oder Standardwerte (der restriktivere Wert wird verwendet). Ablauf des Kanals (sofern vorhanden) als Unix-Zeitstempel (in Millisekunden) in den Informationen, die von der Methode watch zurückgegeben werden. Darüber hinaus enthält der Ablaufdatum und -uhrzeit werden (in visuell lesbarem Format) in jedem Benachrichtigung, die Ihre Anwendung für diesen Kanal in der HTTP-Header „X-Goog-Channel-Expiration“

Derzeit gibt es keine automatische Verlängerung eines Benachrichtigungskanals. Wann? ein Kanal bald abläuft, musst du ihn durch einen neuen ersetzen. Rufe dazu folgenden Link auf: die Methode watch. Wie immer müssen Sie für jedes Element einen eindeutigen Wert verwenden, Das Attribut id des neuen Channels Es gibt wahrscheinlich als „Überlappung“ Zeitraum, in dem die beiden Benachrichtigungskanäle für den Ressource aktiv sind.

Benachrichtigungen erhalten

Immer wenn sich eine beobachtete Ressource ändert, erhält Ihre Anwendung eine eine Benachrichtigung mit einer Beschreibung der Änderung. Die Google Calendar API sendet diese Nachrichten als HTTPS-POST-Anfragen an die URL senden, die Sie als address-Property für diese Benachrichtigung Kanal.

Nachrichtenformat für Benachrichtigungen interpretieren

Alle Benachrichtigungen enthalten eine Reihe von HTTP-Headern mit X-Goog- Präfixe. Einige Benachrichtigungstypen können auch ein Nachrichtentext.

Header

Benachrichtigungen, die von der Google Kalender API an Ihren Empfänger gesendet werden, Die URL enthält die folgenden HTTP-Header:

Header Beschreibung
Immer einblenden
X-Goog-Channel-ID UUID oder ein anderer eindeutiger String, den Sie zur Identifizierung angegeben haben Benachrichtigungskanal.
X-Goog-Message-Number Ganzzahl, die diese Nachricht für diese Benachrichtigung identifiziert Kanal. Der Wert für sync-Nachrichten ist immer 1. Nachricht mit jeder nachfolgenden Nachricht im Kanal erhöht, nicht sequenziell.
X-Goog-Resource-ID Ein intransparenter Wert, der die überwachte Ressource identifiziert. Diese ID lautet in allen API-Versionen stabil sein.
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 Kennung für die überwachte Ressource.
Manchmal anwesend
X-Goog-Channel-Expiration Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals, angegeben in menschenlesbares Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Token des Benachrichtigungskanals, das von Ihrer Anwendung festgelegt wurde, und mit dem Sie die Benachrichtigungsquelle überprüfen können. Nur vorhanden, wenn definiert.

Benachrichtigungen, die von der Google Kalender API an Ihre Ziel-URL gepostet werden, enthalten keinen Nachrichtentext. Diese Nachrichten enthalten keine spezifischen Informationen zu aktualisierten Ressourcen. Sie müssen einen weiteren API-Aufruf ausführen, um die vollständigen Änderungsdetails zu sehen.

Beispiele

Benachrichtigungsnachricht für geänderte Ereignissammlung ändern:

POST https://mydomain.com/notifications // Your receiving URL.
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

Bei erfolgreicher Ausführung 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 gibt 500,502, 503 oder 504, die Google Calendar API, zurück. Wiederholungsversuche mit exponentiellem Backoff. Jeder andere Rückgabestatuscode wird als Nachrichtenfehler betrachtet.

Informationen zu Benachrichtigungsereignissen der Google Calendar API

Dieser Abschnitt enthält Details zu den Benachrichtigungen, die Sie die Sie erhalten, wenn Sie Push-Benachrichtigungen mit der Google Calendar API verwenden.

X-Goog-Resource-State Gilt für Zugestellt, wenn
sync ACLs, Kalenderlisten, Termine, Einstellungen. Ein neuer Kanal wurde erstellt. Du wirst in Zukunft Benachrichtigungen dafür erhalten.
exists ACLs, Kalenderlisten, Termine, Einstellungen. An einer Ressource wurde eine Änderung vorgenommen. Zu den möglichen Änderungen gehören das Erstellen einer neuen Ressource oder das Ändern oder Löschen einer vorhandenen Ressource.

Benachrichtigungen deaktivieren

Mit der Eigenschaft expiration wird festgelegt, wann die Benachrichtigungen automatisch beendet werden. Sie können Du kannst festlegen, dass du für einen bestimmten Kanal keine Benachrichtigungen mehr erhalten möchtest, bevor dieser durch Aufrufen der Methode stop unter den folgenden URI:

https://www.googleapis.com/calendar/v3/channels/stop

Bei dieser Methode müssen Sie mindestens den Typ id- und resourceId-Eigenschaften, wie in den Beispiel unten. Wenn die Google Calendar API über verschiedene Ressourcen mit watch-Methoden, es gibt nur eine stop-Methode.

Nur Nutzer mit der entsprechenden Berechtigung können einen Kanal beenden. Wichtig ist insbesondere:

  • Wurde der Kanal über ein reguläres Nutzerkonto erstellt, werden nur dieselben Nutzer aus dem gleichen Client (identifiziert durch OAuth 2.0-Client-IDs aus der Authentifizierungstokens), die den Kanal erstellt haben, können ihn beenden.
  • Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben kann der Client den Kanal beenden.

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

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

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