Diese Seite wurde von der Cloud Translation API übersetzt.

Push-Benachrichtigungen

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

Ü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 beobachtete Ressource ändert, wird Ihre Anwendung von der Admin SDK API benachrichtigt.

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

Richten Sie die Empfangs-URL oder den Webhook-Rückrufempfänger ein.
Dieser HTTPS-Server verarbeitet die API-Benachrichtigungen, die ausgelöst werden, wenn sich eine Ressource ändert.
Richten Sie einen Benachrichtigungskanal für jeden Ressourcenendpunkt ein, den Sie überwachen möchten.
Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Bei der Kanaleinrichtung musst du die jeweilige 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

Zum Anfordern von Push-Benachrichtigungen müssen Sie für jede Ressource, die Sie überwachen möchten, einen Benachrichtigungskanal einrichten. Nachdem die Benachrichtigungskanäle eingerichtet sind, wird Ihre Anwendung von der Admin SDK API über beobachtete Ressourcenänderungen informiert.

Wiedergabeanfragen stellen

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

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

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

Jeder Benachrichtigungskanal ist sowohl einem bestimmten Nutzer als auch einer bestimmten Ressource (oder Gruppe von Ressourcen) zugeordnet. 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ätenressource 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 aus Gründen der Übersichtlichkeit weggelassen.

Achten Sie auf alle Administratoraktivitäten:

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

Achten Sie auf alle Dokumentaktivitäten:

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

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

Bei jeder watch-Anfrage musst du diese 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 Zeichen

Der von Ihnen festgelegte ID-Wert wird im HTTP-Header X-Goog-Channel-Id jeder Benachrichtigung, die Sie für diesen Kanal erhalten, wieder zurückgegeben.
Ein String des Attributs type, der auf den Wert web_hook festgelegt ist.
Ein String des Attributs address, der auf die URL festgelegt ist, die Benachrichtigungen für diesen Benachrichtigungskanal anhört und darauf antwortet. 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

Du kannst diese optionalen Felder auch in deiner watch-Anfrage angeben:

Eine token-Eigenschaft, die einen beliebigen Stringwert angibt, der als Kanaltoken verwendet werden soll. 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. So lässt sich verhindern, dass die Benachrichtigung gefälscht wird. 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 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.
Hinweis: Wenn Sie vertrauliche Daten senden müssen, müssen Sie dafür sorgen, dass diese verschlüsselt werden, bevor Sie sie dem Token hinzufügen.
Ein expiration-Attributstring, 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 dieser als Wert des HTTP-Headers X-Goog-Channel-Expiration (im visuell lesbaren Format) in jede Benachrichtigung eingefügt, die Ihre 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 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 hat, wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Smartwatch-Antwort 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.
}

Neben den Properties, die Sie im Rahmen der Anfrage gesendet haben, enthalten die zurückgegebenen Informationen auch resourceId und resourceUri zur Identifizierung der Ressource, die von diesem Benachrichtigungskanal beobachtet wird.

Hinweis: Das Attribut resourceId ist eine stabile, versionsunabhängige Kennzeichnung für die 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 weitergeben, 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 Zeitproblemen im Netzwerk kann es sein, dass die Nachricht sync empfangen wird, bevor Sie die Antwort der Methode watch erhalten haben.

Sie können die sync-Benachrichtigung ignorieren, aber Sie können sie 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 einige Initialisierungsschritte auszuführen, um sich auf spätere Ereignisse vorzubereiten.

Das Format der sync-Nachrichten, die die Admin SDK API an die Empfänger-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

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 Standardeinstellungen der Admin SDK API festgelegt (es 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. Darüber hinaus werden das Ablaufdatum und die Ablaufzeit (in visuell lesbarem Format) in jeder Benachrichtigung, die Ihre Anwendung für diesen Kanal erhält, im HTTP-Header X-Goog-Channel-Expiration angegeben.

Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu verlängern. Wenn ein Kanal kurz vor seinem Ablauf steht, müssen Sie ihn durch einen neuen ersetzen. Rufen Sie dazu die Methode watch auf. Wie immer musst du einen eindeutigen Wert für die Eigenschaft id des neuen Kanals verwenden. Beachten Sie, dass es wahrscheinlich einen „Überlappungszeitraum“ gibt, 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.

Hinweis:In HTTPS-Anfragen zur Übermittlung von Benachrichtigungen ist als User-Agent APIs-Google angegeben und es werden robots.txt-Anweisungen berücksichtigt, wie in den APIs des Google-User-Agents für Google beschrieben.

Nachrichtenformat für Benachrichtigungen 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 die empfangende URL gesendet werden, enthalten die folgenden HTTP-Header:

Header	Beschreibung
Immer präsentieren
`X-Goog-Channel-ID`	UUID oder ein anderer eindeutiger String, den Sie zur Identifizierung dieses Benachrichtigungskanals angegeben haben.
`X-Goog-Message-Number`	Ganzzahl, die diese Nachricht für diesen Benachrichtigungskanal identifiziert. Bei `sync`-Nachrichten ist immer `1` der Wert. Bei jeder weiteren Nachricht auf dem Kanal erhöht sich die Nummer der Nachrichten. Sie werden jedoch nicht fortlaufend gesendet.
`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 überwachte Ressource.
Manchmal vorhanden
`X-Goog-Channel-Expiration`	Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in menschenlesbarem Format. Ist nur vorhanden, wenn definiert.
`X-Goog-Channel-Token`	Token des Benachrichtigungskanals, das von Ihrer Anwendung festgelegt wurde und mit dem Sie die Benachrichtigungsquelle prüfen können. Ist nur vorhanden, wenn definiert.

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

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 hat das Datums- und Uhrzeitformat ISO 8601. 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 Qualifier, wenn mehrere Ereignisse dieselbe Zeit haben.
`id.applicationName`	Name der Anwendung, zu der das Ereignis gehört. Folgende Werte sind möglich: admin Kalender Auto Gruppen groups_enterprise login Mobilgerät saml Token user_accounts
`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 Eigentümers des Dokuments in der Google Docs-Anwendung. Dies ist die Domain, die vom Ereignis im Bericht betroffen ist.
`ipAddress`	IP-Adresse des Nutzers, der die Aktion ausführt. Die IP-Adresse (Internet Protocol) des Nutzers bei der Anmeldung in Google Workspace, die den physischen Standort des Nutzers widerspiegeln kann oder nicht. Beispielsweise kann die IP-Adresse 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, den bzw. die ein Administrator ändert, wird in der Property „`type`“ angegeben, die ein Ereignis mithilfe der Property „`eventName`“ identifiziert.
`events[].name`	Name des Ereignisses. Dies ist der spezifische Name der Aktivität, die von der API gemeldet wird. Und jede `eventName` bezieht sich auf einen bestimmten Google Workspace-Dienst oder eine bestimmte Google Workspace-Funktion, die die API in Ereignistypen organisiert. Allgemein für `eventName`-Anfrageparameter: Wenn keine `eventName` angegeben wird, gibt der Bericht alle möglichen Instanzen eines `eventName` zurück. Wenn Sie ein `eventName` anfordern, gibt die API-Antwort alle Aktivitäten zurück, die dieses `eventName` enthalten. Es ist möglich, dass die zurückgegebenen Aktivitäten neben der angefragten noch weitere `eventName`-Eigenschaften haben.
`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 für Ressourcenereignisse vom Typ „Aktivität“ haben folgendes allgemeines 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 Administratoraktivitätsereignis:

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

Wenn der Vorgang erfolgreich war, 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 Admin SDK API den Vorgang mit exponentiellem Backoff. 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: Synchronisierungsmeldungen und Ereignisbenachrichtigungen. Der Nachrichtentyp wird im HTTP-Header X-Goog-Resource-State angegeben. Die möglichen 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 keine Benachrichtigungen mehr für einen bestimmten Kanal 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

Für diese Methode müssen Sie mindestens die Attribute id und resourceId des Kanals angeben, wie im Beispiel unten gezeigt. 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 der Nutzer, der den Kanal erstellt hat, über denselben Client (wie durch die OAuth 2.0-Client-IDs der Authentifizierungstokens identifiziert) den Kanal beenden.
Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben Clients ihn beenden.

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

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"
}