Diese Seite wurde von der Cloud Translation API übersetzt.

Push-Benachrichtigungen

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

Übersicht

Die Admin SDK API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an Ressourcen beobachten können. Sie können dieses Feature verwenden, um die Leistung Ihrer Anwendung zu verbessern. So können Sie zusätzliche Netzwerk- und Rechenkosten vermeiden, die mit Abfrageressourcen verbunden sind, um festzustellen, ob sie sich geändert haben. Immer wenn sich eine beobachtete Ressource ändert, benachrichtigt die Admin SDK API Ihre Anwendung.

Wenn Sie Push-Benachrichtigungen verwenden möchten, müssen Sie zwei Dinge tun:

Richten Sie die Empfangs-URL oder den 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 einen Benachrichtigungskanal für jeden Ressourcenendpunkt ein, den Sie ansehen möchten.
Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Im Rahmen der Kanaleinrichtung gibst du die URL an, unter der du Benachrichtigungen erhalten möchtest. Immer 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 bei Änderungen an der Ressource Activities.

Benachrichtigungskanäle erstellen

Zum Anfordern von Push-Benachrichtigungen musst du einen Benachrichtigungskanal für jede Ressource einrichten, die du ansehen möchtest. Nachdem Sie Ihre Benachrichtigungskanäle eingerichtet haben, informiert die Admin SDK API Ihre Anwendung über Änderungen an den beobachteten Ressourcen.

Smartwatch-Anfragen

Jeder aufrufbaren Admin SDK API-Ressource ist eine watch-Methode mit einem URI im folgenden Format zugeordnet:

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

Zum Einrichten eines Benachrichtigungskanals für Nachrichten zu Änderungen an einer bestimmten Ressource senden Sie eine POST-Anfrage an die Methode watch für die Ressource.

Jeder Benachrichtigungskanal ist sowohl mit einem bestimmten Nutzer als auch mit einer bestimmten Ressource (oder einer Gruppe von Ressourcen) verknüpft. Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder das Dienstkonto der Inhaber dieser Ressource ist oder die Berechtigung zum Zugriff auf diese Ressource hat.

Beispiele

Alle Smartwatch-Anfragen für die Ressource „Aktivitäten“ haben das folgende 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 Text zur besseren Verständlichkeit weggelassen.

Achten Sie auf alle Administratoraktivitäten:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Alle Aktivitäten in Google Docs verfolgen:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Auf bestimmte Administratoraktivitäten achten:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

Achten Sie auf ein bestimmtes Ereignis, zum Beispiel das Ändern des Passworts eines Nutzers:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Achten Sie auf Ä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

Für jede watch-Anfrage müssen Sie Folgendes angeben:

Ein id-Property-String, der diesen neuen Benachrichtigungskanal in deinem Projekt eindeutig identifiziert. Wir empfehlen die Verwendung einer universell eindeutigen Kennung (UUID) oder eines ähnlichen Strings. Maximale Länge: 64 Zeichen.

Der von Ihnen festgelegte ID-Wert wird im HTTP-Header X-Goog-Channel-Id jeder Benachrichtigungsnachricht wiederholt, die Sie für diesen Kanal erhalten.
Ein type-Attributstring, der auf den Wert web_hook festgelegt ist.
Ein address-Property-String, der auf die URL festgelegt ist, die Benachrichtigungen für diesen Benachrichtigungskanal überwacht und darauf reagiert. Dies ist Ihre Webhook-Callback-URL. Sie muss HTTPS verwenden.

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 mit einem Betreff, der nicht mit dem Zielhostnamen übereinstimmt.

Optionale Attribute

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

Ein token-Attribut, das einen beliebigen Stringwert für die Verwendung als Kanaltoken angibt. Benachrichtigungskanal-Tokens können für unterschiedliche Zwecke verwendet werden. Mit dem Token lässt sich beispielsweise überprüfen, ob es sich bei jeder eingehenden Nachricht um einen Kanal handelt, den Ihre Anwendung erstellt hat. So wird sichergestellt, dass die Benachrichtigung nicht gefälscht wird. Außerdem können Sie die Nachricht je nach Zweck dieses Kanals an das richtige Ziel in Ihrer Anwendung weiterleiten. Maximale Länge: 256 Zeichen.
Das Token ist im HTTP-Header X-Goog-Channel-Token in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal erhält.

Wenn Sie Tokens für Benachrichtigungskanäle verwenden, empfehlen wir Folgendes:
- Verwende ein erweiterbares Codierungsformat wie URL-Suchparameter. Beispiel: forwardTo=hr&createdBy=mobile
- Verwenden Sie dabei keine sensiblen Daten wie OAuth-Tokens.
Hinweis: Wenn Sie besonders sensible Daten senden müssen, achten Sie darauf, dass sie verschlüsselt sind, bevor Sie sie dem Token hinzufügen.
Ein expiration-Attributstring, der auf einen Unix-Zeitstempel (in ms) des Datums und der Uhrzeit festgelegt ist, zu dem die Admin SDK API keine Nachrichten mehr für diesen Benachrichtigungskanal senden soll.

Wenn ein Kanal eine Ablaufzeit hat, wird er als Wert für den HTTP-Header X-Goog-Channel-Expiration (dieses Mal im menschenlesbaren Format) in jede Benachrichtigung aufgenommen, die deine Anwendung für diesen Kanal erhält.

Hinweis:Für die Admin SDK API beträgt die maximale Ablaufzeit 21.600 Sekunden. Wenn Sie das Attribut expiration nicht in der Anfrage festlegen, wird die Ablaufzeit standardmäßig auf 21.600 Sekunden nach der aktuellen Uhrzeit festgelegt.

Weitere Informationen zu der Anfrage finden Sie in der API-Referenz zur Methode Activities unter der Methode watch.

Antwort auf Uhr

Wenn die watch-Anfrage erfolgreich einen Benachrichtigungskanal erstellt, wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Watch-Antwort enthält Informationen über den soeben erstellten Benachrichtigungskanal, wie im folgenden Beispiel gezeigt.

{
  "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 Attributen, die Sie im Rahmen Ihrer Anfrage gesendet haben, enthalten die zurückgegebenen Informationen auch resourceId und resourceUri, um die Ressource zu identifizieren, die auf diesem Benachrichtigungskanal beobachtet wird.

Hinweis: Das Attribut resourceId ist eine stabile, versionsunabhängige Kennzeichnung der Ressource. Das Attribut resourceUri ist der kanonische URI der beobachteten Ressource im Kontext der aktuellen API-Version. Es ist also versionsspezifisch.

Sie können die zurückgegebenen Informationen an andere Benachrichtigungskanalvorgänge übergeben, z. B. an das Beenden von Benachrichtigungen.

Weitere Informationen zur Antwort findest du in der API-Referenz zur Methode watch für die Ressource Activities.

Nachricht synchronisieren

Nachdem Sie einen neuen Benachrichtigungskanal zum Ansehen einer Ressource erstellt haben, sendet die Admin SDK API eine sync-Nachricht, die angibt, dass Benachrichtigungen gestartet werden. Der HTTP-Headerwert X-Goog-Resource-State für diese Nachrichten ist sync. Aufgrund von Problemen mit dem Netzwerktiming kann es vorkommen, dass die Nachricht sync schon empfangen wird, bevor du die Antwort der Methode watch erhältst.

Sie können die sync-Benachrichtigung ignorieren, aber Sie können sie auch verwenden. Wenn du beispielsweise den Kanal 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 zur Vorbereitung auf spätere Ereignisse durchzuführen.

Das Format der sync-Nachrichten, die die Admin SDK API an Ihre empfangende 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 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 weitere Benachrichtigung für diesen Kanal hat eine Nachrichtennummer, die größer als die vorherige ist. Die Nachrichtennummern sind jedoch nicht sequenziell.

Benachrichtigungskanäle werden verlängert

Ein Benachrichtigungskanal kann eine Ablaufzeit haben, wobei ein Wert entweder durch Ihre Anfrage oder durch interne Limits oder Standardwerte der Admin SDK API bestimmt wird. Hierbei wird der restriktivere Wert verwendet. Die Ablaufzeit des Kanals (falls vorhanden) wird als Unix-Zeitstempel (in ms) in die von der Methode watch zurückgegebenen Informationen aufgenommen. Außerdem sind Datum und Uhrzeit des Ablaufdatums in für Menschen lesbarer Form in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal im HTTP-Header X-Goog-Channel-Expiration erhält.

Derzeit gibt es keine Möglichkeit, die Benachrichtigungskanäle automatisch zu verlängern. Wenn ein Kanal kurz vor dem Ablauf ist, musst du einen neuen erstellen. Rufe dazu die Methode watch auf. Wie immer musst du für die Property id des neuen Kanals einen eindeutigen Wert verwenden. Es kann wahrscheinlich einen Zeitraum geben, in dem die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.

Benachrichtigungen erhalten

Wenn sich eine überwachte Ressource ändert, erhält die 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 Adresse für diesen Benachrichtigungskanal angegeben haben.

Hinweis: In diesen HTTPS-Anfragen für die Benachrichtigung wird ein User-Agent von APIs-Google angegeben. Außerdem werden die Anweisungen von robots.txt beachtet, wie unter APIs Google User-Agent beschrieben.

Informationen zum Format der Benachrichtigung

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

Header

Benachrichtigungen, die von der Admin SDK API an Ihre empfangende URL gesendet werden, enthalten die folgenden HTTP-Header:

Header	Beschreibung
Immer vorhanden
`X-Goog-Channel-ID`	UUID oder ein anderer eindeutiger String, den Sie angegeben haben, um diesen Benachrichtigungskanal zu identifizieren.
`X-Goog-Message-Number`	Ganzzahl, die diese Nachricht für diesen Benachrichtigungskanal identifiziert. Der Wert für `sync`-Nachrichten ist immer 1. Die Nachrichtennummern erhöhen sich für jede weitere Nachricht auf dem Kanal, sind jedoch nicht sequenziell.
`X-Goog-Resource-ID`	Ein intransparenter Wert, der die beobachtete Ressource identifiziert. Diese ID ist in allen API-Versionen stabil.
`X-Goog-Resource-State`	Der neue Ressourcenstatus, der die Benachrichtigung ausgelöst hat. Mögliche Werte: `sync` oder ein Ereignisname.
`X-Goog-Resource-URI`	Eine API-versionsspezifische Kennung für die beobachtete Ressource.
Manchmal vorhanden
`X-Goog-Channel-Expiration`	Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in für Menschen lesbarem Format. Nur vorhanden, wenn definiert.
`X-Goog-Channel-Token`	Das von Ihrer Anwendung festgelegte Token für den Benachrichtigungskanal, mit dem Sie die Quelle der Benachrichtigung prüfen können. Ist nur vorhanden, wenn definiert.

Benachrichtigungen für Aktivitäten enthalten die folgenden Informationen im Anfragetext:

Attribut	Beschreibung
`kind`	Kennzeichnet dies als Aktivitätsressource. Wert: der feste String "`admin#reports#activity`".
`id`	Eindeutige Kennung des Aktivitätseintrags.
`id.time`	Zeitpunkt des Auftretens der Aktivität. Der Wert liegt im ISO 8601-Format für Datum und Uhrzeit vor. Die Zeit ist das vollständige Datum plus 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 gleichzeitig vorliegen.
`id.applicationName`	Name der Anwendung, zu der das Ereignis gehört Folgende Werte sind möglich: Verwaltung kalender Fahren Gruppen groups_enterprise login Mobilgerät SAML Token nutzerkonten
`id.customerId`	Die eindeutige Kennung für ein Google Workspace-Konto.
`actor`	Nutzer, der die Aktion ausführt.
`actor.callerType`	Die Art des Autors, der die im Bericht aufgeführte Aktivität durchgeführt hat. In diesem API-Version ist `callerType` die Entitätsanfrage `USER` oder OAuth 2LO, 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 Eigentümers des Dokuments in der Google Docs-Anwendung. Das ist die Domain, die vom Ereignis des Berichts betroffen ist.
`ipAddress`	IP-Adresse des Nutzers, der die Aktion ausführt. Das ist die IP-Adresse des Nutzers bei der Anmeldung in Google Workspace, die den physischen Standort des Nutzers ermitteln kann oder nicht. Die IP-Adresse kann z. B. 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 Property `type` identifiziert. Sie identifiziert ein Ereignis mit der Property `eventName`.
`events[].name`	Name des Ereignisses. Dies ist der spezifische Name der von der API gemeldeten Aktivität. Jede `eventName` bezieht sich auf einen bestimmten Google Workspace-Dienst oder eine bestimmte Funktion, die von der API in Arten von Ereignissen organisiert wird. Für `eventName`-Anfrageparameter im Allgemeinen: Wenn kein `eventName` angegeben ist, gibt der Bericht alle möglichen Instanzen eines `eventName` zurück. Wenn Sie eine `eventName` anfordern, gibt die API-Antwort alle Aktivitäten zurück, die diese `eventName` enthalten. Es ist möglich, dass die zurückgegebenen Aktivitäten neben den angeforderten noch weitere `eventName`-Eigenschaften enthalten.
`events[].parameters[]`	Parameterwerte 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 für Ereignisse in Bezug auf Aktivitätsressourcen haben die folgende allgemeine Form:

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 mit Administratoraktivitäten:

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

Für einen erfolgreichen Erfolg 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 den Versuch mit exponentiellem Backoff. Jeder andere Rückgabestatuscode gilt als Nachrichtenfehler.

Benachrichtigungsereignisse für die 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.

Es gibt zwei Arten von Push-Benachrichtigungen in der Reports API: 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 werden beendet

Die Ablaufzeit gibt an, wann die Benachrichtigungen automatisch beendet werden. Du kannst die Benachrichtigungen für einen bestimmten Kanal beenden, bevor er abläuft. Rufe dazu die Methode stop unter folgendem URI auf:

https://www.googleapis.com/admin/reports_v1/channels/stop

Für diese Methode musst du mindestens die Properties id und resourceId des Kanals angeben, wie im Beispiel unten gezeigt. Hinweis: Auch wenn die Admin SDK API mehrere Arten von Ressourcen 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 er nur von demselben Nutzer über denselben Client (an den OAuth 2.0-Client-IDs aus den Authentifizierungstokens identifiziert) wie zuvor erstellt werden.
Wenn der Kanal von einem Dienstkonto erstellt wurde, können alle Nutzer vom selben Client den Kanal beenden.

POST https://www.googleapis.com/admin/reports_v1/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

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