Push-Benachrichtigungen

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

Übersicht

Die Admin SDK API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an Ressourcen überwachen können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. So können Sie die zusätzlichen Netzwerk- und Rechenkosten vermeiden, die beim Abrufen von Ressourcen anfallen, 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 Dinge tun:

  • Richten Sie Ihre Empfangs-URL oder den Callback-Empfänger für Webhooks 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 Channel gibt Routinginformationen für Benachrichtigungsnachrichten an. Im Rahmen der Einrichtung des Channels müssen Sie die spezifische URL angeben, an die Sie Benachrichtigungen erhalten möchten. 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 für Ä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 Sie Ihre Benachrichtigungschannels eingerichtet haben, informiert die Admin SDK API Ihre Anwendung, wenn sich eine überwachte Ressource ändert.

Anfragen zur Wiedergabe stellen

Jeder beobachtbaren Admin SDK API-Ressource ist eine watch-Methode unter einem URI der folgenden Form zugeordnet:

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

Wenn Sie einen Benachrichtigungskanal für Nachrichten zu Ä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 Gruppe von Ressourcen) zugeordnet. Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder das Dienstkonto Eigentümer dieser Ressource ist oder die Berechtigung hat, darauf zuzugreifen.

Beispiele

Alle Überwachungsanfragen für die Ressource „Activities“ haben die allgemeine Form:

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

Der Anfragetext hat die folgenden Eigenschaften:

  • id: Eine UUID oder ein ähnlicher eindeutiger String, der diesen Channel identifiziert.
  • type: Der Typ des Bereitstellungsmechanismus. Der Wert für dieses Feld muss web_hook sein.
  • address: Die URL, an die Benachrichtigungen gesendet werden.
  • token: Ein beliebiger String, der mit jeder Benachrichtigung an die Zieladresse gesendet wird, um zu überprüfen, ob die Benachrichtigung von einer vertrauenswürdigen Quelle stammt.
  • payload: Ein boolescher Wert, der angibt, ob die Nutzlast in die Benachrichtigung aufgenommen werden soll.
  • expiration: Die Gültigkeitsdauer des Benachrichtigungskanals in Sekunden.

Mit den Parametern userKey, applicationName, eventName und filters können Sie festlegen, dass Sie nur Benachrichtigungen für bestimmte Ereignisse, Nutzer oder Anwendungen erhalten.

Hinweis:In den folgenden Beispielen wird der Anfragetext zur besseren Übersichtlichkeit weggelassen.

Alle Administratoraktivitäten beobachten:

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

Alle Aktivitäten in Google Docs beobachten:

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

Administratoraktivitäten eines bestimmten Nutzers beobachten:

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

Nach einem bestimmten Ereignis suchen, z. B. wenn das Passwort eines Nutzers geändert wird:

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

Nach Änderungen an einem bestimmten Dokument suchen:

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 die folgenden Felder angeben:

  • Ein id-Attributstring, der diesen neuen Benachrichtigungskanal in Ihrem Projekt eindeutig identifiziert. Wir empfehlen, eine 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 Benachrichtigungsnachricht, die Sie für diesen Kanal erhalten, zurückgegeben.

  • 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 empfängt und darauf reagiert. Dies ist die Callback-URL Ihres Webhooks. 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, deren Subjekt nicht mit dem Zielhostname übereinstimmt.

Optionale Attribute

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

  • Eine token-Eigenschaft, die einen beliebigen Stringwert angibt, der als Channel-Token verwendet werden soll. Tokens für Benachrichtigungschannels können für verschiedene Zwecke verwendet werden. 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 lässt sich sicherstellen, dass die Benachrichtigung nicht gefälscht wird. Außerdem können Sie die Nachricht basierend auf dem Zweck des Kanals an das richtige Ziel in Ihrer Anwendung weiterleiten. Maximale Länge: 256 Zeichen.

    Das Token ist in jeder Benachrichtigungsnachricht, die Ihre Anwendung für diesen Kanal empfängt, im X-Goog-Channel-Token-HTTP-Header enthalten.

    Wenn Sie Benachrichtigungschannel-Tokens verwenden, empfehlen wir Ihnen Folgendes:

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

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

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

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

Weitere Informationen zur Anfrage finden Sie in der API-Referenz in der Beschreibung der Methode watch für die Ressource Activities.

Antwort auf der Smartwatch ansehen

Wenn durch die watch-Anfrage erfolgreich ein Benachrichtigungschannel erstellt wird, wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Smartwatch-Antwort enthält Informationen zum Benachrichtigungskanal, den du gerade erstellt hast, wie im Beispiel unten gezeigt.

{
  "kind": "api#channel",
  "id": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

Zusätzlich zu den Eigenschaften, 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.

Sie können die zurückgegebenen Informationen an andere Benachrichtigungschannel-Vorgä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.

Synchronisierungsnachricht

Nachdem Sie einen Benachrichtigungskanal zum Beobachten einer Ressource erstellt haben, sendet die Admin SDK 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 Meldung sync erhalten, bevor Sie die Antwort der Methode watch erhalten.

Sie können die Benachrichtigung sync ignorieren, aber 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 zum Beenden des Empfangs von Benachrichtigungen verwenden. Sie können die sync-Benachrichtigung auch verwenden, um einige Initialisierungen vorzubereiten, die für spätere Ereignisse erforderlich sind.

Das Format von sync-Nachrichten, die von der Admin SDK API an Ihre Empfangs-URL gesendet werden, 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-Headerwert 1. Jede nachfolgende Benachrichtigung für diesen Channel hat eine Nachrichtennummer, die größer als die vorherige ist. Die Nachrichtennummern sind jedoch nicht fortlaufend.

Benachrichtigungskanäle erneuern

Ein Benachrichtigungschannel kann eine Ablaufzeit haben, deren Wert entweder durch Ihre Anfrage oder durch interne Grenzwerte oder Standardwerte der Admin SDK API bestimmt wird (der restriktivere Wert wird verwendet). Die Ablaufzeit des Kanals, sofern vorhanden, ist als Unix-Zeitstempel (in Millisekunden) in den Informationen enthalten, die von der Methode watch zurückgegeben werden. Außerdem sind das Ablaufdatum und die Ablaufzeit (im für Menschen lesbaren Format) in jeder Benachrichtigungsnachricht enthalten, die Ihre Anwendung für diesen Channel im HTTP-Header X-Goog-Channel-Expiration empfängt.

Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu verlängern. Wenn ein Channel bald abläuft, müssen Sie ihn durch einen neuen ersetzen. Rufen Sie dazu die watch-Methode auf. Wie immer müssen Sie für die Property id des neuen Channels 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 Benachrichtigung mit einer Beschreibung der Änderung. Die Admin SDK API sendet diese Nachrichten als HTTPS-POST-Anfragen an die URL, die Sie als address-Property für diesen Benachrichtigungschannel angegeben haben.

Format der Benachrichtigungsnachricht 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
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 auf dem 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 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 Benachrichtigungschannels im für Menschen lesbaren Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Das von Ihrer Anwendung festgelegte Benachrichtigungschannel-Token, mit dem Sie die Benachrichtigungsquelle überprüfen können. Nur vorhanden, wenn definiert.

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

Attribut Beschreibung
kind Gibt an, dass es sich um eine Activity-Ressource handelt. Wert: Der feste String „admin#reports#activity“.
id Eindeutige Kennung des Aktivitätsdatensatzes.
id.time Zeitpunkt des Auftretens der Aktivität. Der Wert ist im Datums- und Zeitformat nach ISO 8601. Die Zeit ist das vollständige Datum plus Stunden, Minuten und Sekunden im Format JJJJ-MM-TTThh:mm:ssZZZ. Beispiel: 2010-04-05T17:30:04+01:00.
id.uniqueQualifier Eindeutiger Qualifikator, wenn mehrere Ereignisse zur selben Zeit stattfinden.
id.applicationName Name der Anwendung, zu der das Ereignis gehört. Mögliche Werte:
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 ausgefü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 Dokumentinhabers der Docs-Anwendung. Dies ist die Domain, die vom Ereignis des Berichts betroffen ist.
ipAddress IP-Adresse des Nutzers, der die Aktion ausführt. Dies ist die IP-Adresse des Nutzers bei der Anmeldung in Google Workspace. Sie kann den physischen Standort des Nutzers angeben, muss es aber 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 Property type angegeben, die ein Ereignis mithilfe der Property eventName identifiziert.
events[].name Name des Ereignisses. 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.
Für eventName-Anfrageparameter im Allgemeinen:
  • Wenn kein eventName angegeben ist, werden im Bericht alle möglichen Instanzen eines eventName zurückgegeben.
  • Wenn Sie ein eventName anfordern, werden in der Antwort der API alle Aktivitäten zurückgegeben, die dieses eventName enthalten. Es ist möglich, dass die zurückgegebenen Aktivitäten neben der angeforderten auch andere eventName-Attribute 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 Ereignisse der Aktivitätsressource haben das folgende allgemeine Format:

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

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, werden die Admin SDK API-Aufrufe mit exponentiellem Backoff wiederholt. Jeder andere Rückgabestatuscode gilt als Nachrichtenfehler.

Benachrichtigungsereignisse der Admin SDK API

In diesem Abschnitt finden Sie Details zu den Benachrichtigungen, die Sie bei der Verwendung von Push-Benachrichtigungen mit der Admin SDK API erhalten können.

Push-Benachrichtigungen für die Reports API enthalten zwei Arten von Nachrichten: sync-Nachrichten und Ereignisbenachrichtigungen. Der Nachrichtentyp wird im HTTP-Header X-Goog-Resource-State angegeben. Die möglichen Werte für Event-Benachrichtigungen sind dieselben wie für die Methode activities.list. Jede Anwendung hat eindeutige Ereignisse:

Benachrichtigungen deaktivieren

Mit der Eigenschaft expiration wird gesteuert, wann die Benachrichtigungen automatisch beendet werden. Sie können Benachrichtigungen für einen bestimmten Kanal deaktivieren, bevor er abläuft, indem Sie 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 über ein reguläres Nutzerkonto erstellt wurde, kann er nur von demselben Nutzer über denselben Client (identifiziert durch die OAuth 2.0-Client-IDs aus den Autorisierungstokens) beendet werden, der den Kanal erstellt hat.
  • Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben Clients den Kanal beenden.

Das folgende Codebeispiel zeigt, wie Sie den Empfang von Benachrichtigungen beenden:

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