In diesem Dokument wird beschrieben, wie Sie Push-Benachrichtigungen verwenden, um Ihre Anwendung über Änderungen an einer Ressource zu informieren.
Überblick
Die Admin SDK API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an Ressourcen überwachen können. Mit diesem Feature können Sie die Leistung Ihrer Anwendung verbessern. Sie können die zusätzlichen Netzwerk- und Rechenkosten für das Abfragen von Ressourcen eliminieren, um festzustellen, ob sie sich geändert haben. Wenn sich eine überwachte Ressource ändert, benachrichtigt die Admin SDK API Ihre Anwendung.
Wenn Sie Push-Benachrichtigungen verwenden möchten, müssen Sie zwei Schritte ausführen:
Richten Sie Ihre Empfangs-URL oder einen „Webhook“-Callback-Empfänger ein.
Dies ist ein HTTPS-Server, der die API-Benachrichtigungen verarbeitet, die ausgelöst werden, wenn sich eine Ressource ändert.
Richten Sie für jeden Ressourcenendpunkt, den Sie beobachten möchten, einen Benachrichtigungskanal ein.
Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Bei der Kanaleinrichtung musst du die URL angeben, unter der du Benachrichtigungen erhalten möchtest. Wenn sich die Ressource eines Kanals ändert, sendet die Admin SDK API eine Benachrichtigung als
POST
-Anfrage an diese URL.
Derzeit unterstützt die Admin SDK API Benachrichtigungen über Änderungen an der Ressource Activities.
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 die Benachrichtigungskanäle eingerichtet sind, informiert die Admin SDK API Ihre Anwendung über beobachtete Ressourcenänderungen.
Wiedergabeanfragen senden
Jede Watchable Admin SDK API-Ressource ist mit einer watch
-Methode mit einem URI der folgenden Form verknüpft:
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 Methode watch
für die Ressource.
Jeder Benachrichtigungskanal ist sowohl mit einem bestimmten Nutzer als auch einer bestimmten Ressource (oder Gruppe von Ressourcen) verknüpft. Eine watch
-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder das aktuelle Dienstkonto Inhaber oder Zugriffsberechtigung für diese Ressource hat.
Beispiele
Alle Überwachungsanfragen für die Aktivitätsressource haben das allgemeine Format:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/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-myFilesChannelDest", // (Optional) Your channel token. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
Sie können die Parameter userKey, applicationName, eventName
und filters
verwenden, um nur Benachrichtigungen für bestimmte Ereignisse, Nutzer oder Anwendungen zu erhalten.
Hinweis:In den folgenden Beispielen wird der Anfragetext zur Verdeutlichung weggelassen.
Achten Sie auf alle Administratoraktivitäten:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Beobachten Sie alle Aktivitäten zu Dokumenten:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Achten Sie auf die Administratoraktivitäten eines bestimmten Nutzers:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Achten Sie auf ein bestimmtes Ereignis, z. B. das Ändern des Nutzerpassworts:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
Suchen Sie nach Änderungen an einem bestimmten Dokument:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
Erforderliche Properties
Bei jeder watch
-Anfrage müssen Sie folgende Felder angeben:
-
Ein
id
-Attributstring, der diesen neuen Benachrichtigungskanal in Ihrem Projekt eindeutig identifiziert. Wir empfehlen die Verwendung einer UUID (Universally Unique Identifier) oder eines ähnlichen eindeutigen Strings. Maximale Länge: 64 ZeichenDer von Ihnen festgelegte ID-Wert wird im HTTP-Header
X-Goog-Channel-Id
jeder Benachrichtigung, die Sie für diesen Kanal erhalten, zurückgegeben. -
Ein
type
-Attributstring mit dem Wertweb_hook
. -
Ein
address
-Property-String, der auf die URL festgelegt ist, die Benachrichtigungen für diesen Benachrichtigungskanal erfasst und darauf antwortet. Dies ist die Webhook-Callback-URL, die HTTPS verwenden muss.Die Admin SDK 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 Zielhostnamen übereinstimmt.
Optionale Attribute
Du kannst diese optionalen Felder auch mit deiner watch
-Anfrage angeben:
-
Ein
token
-Attribut, das einen beliebigen Stringwert zur Verwendung als Kanaltoken angibt. Sie können Tokens für Benachrichtigungskanäle für verschiedene Zwecke verwenden. Mit dem Token können Sie beispielsweise prüfen, ob jede eingehende Nachricht zu einem von Ihrer Anwendung erstellten Kanal gehört, um sicherzustellen, dass die Benachrichtigung nicht gefälscht wird. Alternativ können Sie die Nachricht je nach Zweck dieses Kanals an das richtige Ziel innerhalb Ihrer Anwendung weiterleiten. Maximale Länge: 256 ZeichenDas Token ist im HTTP-Header
X-Goog-Channel-Token
in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal empfängt.Wenn Sie Tokens für Benachrichtigungskanäle verwenden, empfehlen wir Folgendes:
Verwenden Sie ein erweiterbares Codierungsformat, z. B. URL-Suchparameter. Beispiel:
forwardTo=hr&createdBy=mobile
Geben Sie keine sensiblen Daten wie OAuth-Tokens an.
-
Ein
expiration
-Property-String, der auf einen Unix-Zeitstempel (in Millisekunden) für das Datum und die Uhrzeit festgelegt ist, zu der die Admin SDK API keine Nachrichten mehr für diesen Benachrichtigungskanal senden soll.Wenn ein Kanal eine Ablaufzeit hat, wird er (im visuell lesbaren Format) als Wert des HTTP-Headers
X-Goog-Channel-Expiration
in jede Benachrichtigung eingefügt, die Ihre Anwendung für diesen Kanal empfängt.
Weitere Informationen zur Anfrage finden Sie in der API-Referenz in der Methode watch
für die Ressource Activities.
Antwort ansehen
Wenn die watch
-Anfrage erfolgreich einen Benachrichtigungskanal erstellt, wird der HTTP-Statuscode 200 OK
zurückgegeben.
Der Nachrichtentext der Überwachungsantwort enthält Informationen über den gerade erstellten Benachrichtigungskanal, wie im folgenden Beispiel dargestellt.
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
Zusätzlich zu den Properties, die du im Rahmen der Anfrage gesendet hast, enthalten die zurückgegebenen Informationen auch resourceId
und resourceUri
zur Identifizierung der Ressource, die in diesem Benachrichtigungskanal beobachtet wird.
Sie können die zurückgegebenen Informationen an andere Benachrichtigungskanalvorgänge übergeben, z. B. wenn Sie keine Benachrichtigungen mehr erhalten möchten.
Weitere Informationen zur Antwort finden Sie in der API-Referenz in der Methode watch
für die Ressource Activities.
Nachricht synchronisieren
Nachdem Sie einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt haben, sendet die Admin SDK API eine sync
-Nachricht, um anzugeben, dass Benachrichtigungen gestartet werden. Der X-Goog-Resource-State
-HTTP-Header-Wert für diese Nachrichten lautet sync
. Aufgrund von Problemen mit dem Netzwerk-Timing kann es sein, dass die sync
-Nachricht bereits empfangen wird, bevor Sie die Antwort der watch
-Methode erhalten.
Sie können die sync
-Benachrichtigung ignorieren, Sie können sie aber auch verwenden. Wenn du den Kanal beispielsweise nicht behalten möchtest, kannst du die Werte X-Goog-Channel-ID
und X-Goog-Resource-ID
in einem Aufruf verwenden, um keine Benachrichtigungen mehr zu erhalten. Sie können auch die Benachrichtigung sync
verwenden, um eine Initialisierung durchzuführen, um sich auf spätere Ereignisse vorzubereiten.
Das Format der sync
-Nachrichten, die die Admin SDK API an die Empfänger-URL sendet, 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 den X-Goog-Message-Number
-HTTP-Header-Wert 1
. Jede nachfolgende Benachrichtigung für diesen Kanal hat eine größere Nachrichtennummer als die vorherige. Die Nachrichtennummern sind jedoch nicht fortlaufend.
Benachrichtigungskanäle verlängern
Ein Benachrichtigungskanal kann eine Ablaufzeit haben. Der Wert wird entweder durch Ihre Anfrage oder durch interne Limits oder Standardwerte der Admin SDK API festgelegt. Dabei wird der restriktivere Wert verwendet. Die Ablaufzeit des Kanals, falls vorhanden, wird als Unix-Zeitstempel (in Millisekunden) in die Informationen aufgenommen, die von der Methode watch
zurückgegeben werden. Außerdem sind das Ablaufdatum und die Ablaufzeit (in menschenlesbarem Format) in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal im HTTP-Header X-Goog-Channel-Expiration
erhält.
Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu verlängern. Kurz vor Ablauf eines Kanals müssen Sie ihn durch einen neuen ersetzen. Dazu rufen Sie die Methode watch
auf. Wie immer musst du einen eindeutigen Wert für die id
-Property des neuen Kanals verwenden. Beachten Sie, dass es wahrscheinlich einen „Überlappungszeitraum“ geben kann, in dem die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.
Benachrichtigungen erhalten
Immer wenn sich eine überwachte Ressource ändert, erhält Ihre Anwendung eine Benachrichtigung, in der die Änderung beschrieben wird. Die Admin SDK API sendet diese Nachrichten als HTTPS-POST
-Anfragen an die URL, die Sie als Property address
für diesen Benachrichtigungskanal angegeben haben.
Format der Benachrichtigung interpretieren
Alle Benachrichtigungen enthalten eine Reihe von HTTP-Headern mit dem Präfix X-Goog-
.
Einige Arten von Benachrichtigungen können auch einen Nachrichtentext enthalten.
Header
Benachrichtigungen, die von der Admin SDK API an Ihre Empfangs-URL gesendet werden, enthalten die folgenden HTTP-Header:
Header | Beschreibung |
---|---|
Immer vorhanden | |
|
UUID oder ein anderer eindeutiger String, den Sie angegeben haben, um diesen Benachrichtigungskanal zu identifizieren. |
|
Ganzzahl, die diese Nachricht für diesen Benachrichtigungskanal identifiziert. Der Wert für sync -Nachrichten ist immer 1 . Bei jeder weiteren Nachricht auf dem Kanal erhöht sich die Anzahl der Nachrichten. Sie werden jedoch nicht fortlaufend gesendet. |
|
Ein intransparenter Wert, der die beobachtete Ressource identifiziert. Diese ID ist in allen API-Versionen stabil. |
|
Der neue Ressourcenstatus, der die Benachrichtigung ausgelöst hat.
Mögliche Werte: sync oder ein Ereignisname.
|
|
Eine API-versionsspezifische Kennung für die überwachte Ressource. |
Gelegentlich vorhanden | |
|
Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in einem für Menschen lesbaren Format. Ist nur vorhanden, wenn definiert. |
|
Das von Ihrer Anwendung festgelegte Benachrichtigungskanaltoken, mit dem Sie die Benachrichtigungsquelle prüfen können. Ist nur vorhanden, wenn definiert. |
Benachrichtigungen für Aktivitäten enthalten die folgenden Informationen im Anfragetext:
Property | Beschreibung |
---|---|
kind |
Kennzeichnet dies als Aktivitätsressource. Wert: der feste String "admin#reports#activity " |
id |
Eindeutige Kennung des Aktivitätsdatensatzes. |
id.time |
Zeitpunkt des Auftretens der Aktivität. Der Wert liegt im ISO 8601-Format für Datum und Uhrzeit. Die Uhrzeit ist das vollständige Datum mit Stunden, Minuten und Sekunden im Format JJJJ-MM-TTThh:mm:ssTZD. Beispiel: 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
Eindeutiger Kennzeichner, wenn mehrere Ereignisse dieselbe Zeit haben. |
id.applicationName |
Name der Anwendung, zu der das Ereignis gehört. Folgende Werte sind möglich: |
id.customerId |
Die eindeutige Kennung für ein Google Workspace-Konto. |
actor |
Nutzer, der die Aktion ausführt. |
actor.callerType |
Der Typ des Autors, der die im Bericht aufgeführte Aktivität durchgeführt hat. In dieser Version der API ist callerType die USER - oder OAuth 2LO-Entitätsanfrage, die die im Bericht aufgeführte Aktion ausgeführt hat . |
actor.email |
Die primäre E-Mail-Adresse des Nutzers, dessen Aktivitäten gemeldet werden. |
actor.profileId |
Die eindeutige Google Workspace-Profil-ID des Nutzers. |
ownerDomain |
Domain der Admin-Konsole oder des Dokumenteigentümers der Google Docs-Anwendung. Das ist die Domain, die vom Ereignis im Bericht betroffen ist. |
ipAddress |
IP-Adresse des Nutzers, der die Aktion ausführt Dies ist die Internet Protocol-Adresse (IP-Adresse) des Nutzers bei der Anmeldung in Google Workspace, die den physischen Standort des Nutzers widerspiegeln kann oder nicht. Die IP-Adresse kann beispielsweise die Adresse des Proxyservers des Nutzers oder die Adresse eines virtuellen privaten Netzwerks (VPN) sein. Die API unterstützt IPv4 und IPv6. |
events[] |
Aktivitätsereignisse im Bericht. |
events[].type |
Ereignistyp. Der Google Workspace-Dienst oder die Google Workspace-Funktion, die ein Administrator ändert, wird in der type -Property angegeben, die ein Ereignis mithilfe der eventName -Property identifiziert. |
events[].name |
Name des Ereignisses. Dies ist der spezifische Name der Aktivität, die von der API gemeldet wird. Jede eventName bezieht sich auf einen bestimmten Google Workspace-Dienst oder eine bestimmte Funktion, die von der API in Ereignistypen organisiert wird.
Allgemein für eventName -Anfrageparameter gilt:
|
events[].parameters[] |
Parameterwertpaare für verschiedene Anwendungen. |
events[].parameters[].name |
Name des Parameters. |
events[].parameters[].value |
Stringwert des Parameters. |
events[].parameters[].intValue |
Ganzzahlwert des Parameters. |
events[].parameters[].boolValue |
Boolescher Wert des Parameters. |
Beispiele
Benachrichtigungen zu Aktivitätsressourcenereignissen haben das allgemeine Format:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
Beispiel für ein Ereignis einer Administratoraktivität:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.com" } ] } ] }
Auf Benachrichtigungen reagieren
Zur Anzeige des Erfolgs 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, versucht die Admin SDK API, Wiederholungsversuche mit exponentiellem Backoff auszuführen.
Jeder andere Rückgabestatuscode gilt als Nachrichtenfehler.
Benachrichtigungsereignisse der Admin SDK API
Dieser Abschnitt enthält Details zu den Benachrichtigungen, die Sie erhalten können, wenn Sie Push-Benachrichtigungen mit der Admin SDK API verwenden.
Push-Benachrichtigungen der Reports API enthalten zwei Arten von Nachrichten: Synchronisierungsnachrichten und Ereignisbenachrichtigungen. Der Nachrichtentyp wird im HTTP-Header X-Goog-Resource-State
angegeben. Mögliche Werte für Ereignisbenachrichtigungen sind dieselben wie für die Methode activities.list
. Jede Anwendung hat eindeutige Ereignisse:
Benachrichtigungen deaktivieren
Mit der Eigenschaft expiration
wird festgelegt, wann die Benachrichtigungen automatisch beendet werden. Wenn du für einen bestimmten Kanal keine Benachrichtigungen mehr erhalten möchtest, bevor er abläuft, kannst du die Methode stop
unter dem folgenden URI aufrufen:
https://www.googleapis.com/admin/reports_v1/channels/stop
Bei dieser Methode musst du mindestens die Properties id
und resourceId
des Kanals angeben, wie im folgenden Beispiel gezeigt. Hinweis: Wenn die Admin SDK API mehrere Ressourcentypen mit watch
-Methoden hat, gibt es nur eine stop
-Methode.
Nur Nutzer mit der entsprechenden Berechtigung können einen Kanal beenden. Wichtig ist insbesondere:
- Wenn der Kanal von einem regulären Nutzerkonto erstellt wurde, kann nur derselbe Nutzer aus demselben Client (wie durch die OAuth 2.0-Client-IDs der Authentifizierungstokens identifiziert), der den Kanal erstellt hat, den Kanal beenden.
- Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben Clients ihn beenden.
Das folgende Codebeispiel zeigt, wie Sie den Empfang von Benachrichtigungen deaktivieren:
POST https://www.googleapis.com/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }