Push-Benachrichtigungen

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

Übersicht

Die Directory API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an Ressourcen im Blick behalten können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. So lassen sich die zusätzlichen Netzwerk- und Rechenkosten vermeiden, die durch das Abfragen von Ressourcen entstehen, um festzustellen, ob sie sich geändert haben. Sobald sich eine beobachtete Ressource ändert, benachrichtigt die Directory API Ihre Anwendung.

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

  • Richten Sie die Empfänger-URL oder den Webhook-Callback-Empfänger ein.

    Dies ist ein HTTPS-Server, der die API-Benachrichtigungsnachrichten verarbeitet, die bei einer Ressourcenänderung ausgelöst werden.

  • Richten Sie für jeden Ressourcenendpunkt, den Sie beobachten möchten, einen Benachrichtigungskanal ein.

    Ein Kanal gibt Routinginformationen für Benachrichtigungsnachrichten an. Im Rahmen der Kanaleinrichtung müssen Sie die URL angeben, unter der Sie Benachrichtigungen erhalten möchten. Jedes Mal, wenn sich die Ressource eines Kanals ändert, sendet die Directory API eine Benachrichtigungsnachricht als POST-Anfrage an diese URL.

Derzeit unterstützt die Directory API Benachrichtigungen bei Änderungen an der Ressource Nutzer.

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 Benachrichtigungskanäle eingerichtet haben, benachrichtigt die Directory API Ihre Anwendung, wenn sich eine beobachtete Ressource ändert.

Smartwatch-Anfragen stellen

Jede abwählbare Directory API-Ressource hat eine zugehörige watch-Methode unter einer URI mit folgendem Format:

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 mit einem bestimmten Nutzer als auch mit einer bestimmten Ressource (oder einer Gruppe von Ressourcen) verknüpft. Eine watch-Anfrage ist nur dann erfolgreich, wenn der aktuelle Nutzer oder das aktuelle Dienstkonto Eigentümer der Ressource ist oder die Berechtigung zum Zugriff darauf hat.

Beispiele

Alle Beobachtungsanfragen für die User-Ressource für eine einzelne Domain haben die allgemeine Form:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Verwenden Sie die Parameter domain und event, um die Domain und den Ereignistyp anzugeben, für den Sie Benachrichtigungen erhalten möchten.

Alle Anfragen zum Überwachen der Nutzerressource für einen Kunden haben die allgemeine Form:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Mit den Parametern customer und event kannst du die eindeutige ID des Google-Kontos des Kunden und den Ereignistyp angeben, für den du Benachrichtigungen erhalten möchtest.

Folgende Werte sind für event möglich:

  • add: vom Nutzer erstelltes Ereignis
  • delete: Ereignis „Nutzer gelöscht“
  • makeAdmin: Ereignis „Änderung des Status des Nutzeradministrators“
  • undelete: Ereignis „Nutzer hat gelöschte Elemente wiederhergestellt“
  • update: vom Nutzer aktualisiertes Ereignis

Hinweis:In den folgenden Beispielen wird der Anfragetext zur besseren Verständlichkeit weggelassen.

Achten Sie auf von Nutzern erstellte Ereignisse für die Domain mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Achten Sie auf von Nutzern erstellte Ereignisse für den Kunden my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

Erforderliche Properties

Bei jeder watch-Anfrage müssen Sie die folgenden Felder angeben:

  • Ein id-Attributstring, der diesen neuen Benachrichtigungskanal innerhalb Ihres Projekts eindeutig identifiziert. Wir empfehlen die Verwendung einer Universally Unique Identifier (UUID) oder eines ähnlichen eindeutigen Strings. 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-Attribut-String, 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 Ihre Webhook-Callback-URL und sie muss HTTPS verwenden.

    Die Directory API kann Benachrichtigungen nur 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 Inhaber nicht mit dem Zielhostnamen übereinstimmt.

Optionale Attribute

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

  • Eine token-Property, die einen beliebigen Stringwert angibt, der als Kanaltoken verwendet werden soll. Sie können Benachrichtigungskanal-Tokens für verschiedene Zwecke verwenden. Sie können das Token beispielsweise verwenden, um zu prüfen, ob jede eingehende Nachricht für einen Kanal bestimmt ist, den Ihre Anwendung erstellt hat, um sicherzustellen, dass die Benachrichtigung nicht gefälscht wird, oder um die Nachricht basierend auf dem Zweck dieses Kanals an das richtige Ziel innerhalb Ihrer Anwendung weiterzuleiten. Maximale Länge: 256 Zeichen.

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

    Wenn Sie Benachrichtigungskanal-Tokens verwenden, empfehlen wir Folgendes:

    • Verwenden Sie ein erweiterbares Codierungsformat, z. B. 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, ab dem die Directory API keine Nachrichten mehr für diesen Benachrichtigungskanal senden soll.

    Wenn ein Kanal ein Ablaufdatum hat, wird es in jeder Benachrichtigungsnachricht, die Ihre Anwendung für diesen Kanal empfängt, als Wert des X-Goog-Channel-Expiration-HTTP-Headers (in einem visuell lesbaren Format) angegeben.

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

Antwort auf Smartwatch

Wenn mit der watch-Anfrage ein Benachrichtigungskanal erstellt wurde, wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Smartwatch-Antwort enthält Informationen zum gerade erstellten Benachrichtigungskanal, wie im folgenden Beispiel gezeigt.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

Zusätzlich zu den Eigenschaften, die du im Rahmen deiner Anfrage gesendet hast, enthalten die zurückgegebenen Informationen auch resourceId und resourceUri, um die Ressource zu identifizieren, die auf diesem Benachrichtigungskanal angesehen wird.

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 findest du in der API-Referenz unter der Methode watch für die Ressource Nutzer.

Synchronisierungsnachricht

Nachdem Sie einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt haben, sendet die Directory API eine sync-Nachricht, um anzuzeigen, dass Benachrichtigungen gestartet werden. Der Wert des X-Goog-Resource-State-HTTP-Headers für diese Nachrichten ist sync. Aufgrund von Netzwerkzeitproblemen ist es möglich, dass Sie die sync-Nachricht erhalten, bevor Sie die Antwort der watch-Methode erhalten.

Sie können die sync-Benachrichtigung ignorieren, sie aber auch verwenden. Wenn Sie den Kanal beispielsweise nicht mehr verwenden möchten, können Sie die Werte X-Goog-Channel-ID und X-Goog-Resource-ID in einem Anruf verwenden, um keine Benachrichtigungen mehr zu erhalten. Sie können die Benachrichtigung sync auch verwenden, um eine Initialisierung durchzuführen und sich auf spätere Ereignisse vorzubereiten.

Unten sehen Sie das Format der sync-Nachrichten, die die Directory API an Ihre Empfänger-URL sendet.

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

Synchronisationsnachrichten haben immer den Wert 1 für den X-Goog-Message-Number-HTTP-Header. Jede nachfolgende Benachrichtigung für diesen Channel hat eine Nachrichtennummer, die höher als die vorherige ist. Die Nachrichtennummern sind jedoch nicht fortlaufend.

Benachrichtigungskanäle verlängern

Ein Benachrichtigungskanal kann eine Ablaufzeit haben, deren Wert entweder durch Ihre Anfrage oder durch interne Limits oder Standardwerte der Directory API bestimmt wird. Es wird der jeweils strengste Wert verwendet. Das Ablaufdatum des Kanals (falls vorhanden) ist in den Informationen, die von der watch-Methode zurückgegeben werden, als Unix-Zeitstempel (in Millisekunden) enthalten. Außerdem sind das Ablaufdatum und die Ablaufzeit (in einem für Menschen lesbaren Format) in jeder Benachrichtigungsnachricht, die deine Anwendung für diesen Kanal im X-Goog-Channel-Expiration-HTTP-Header empfängt, enthalten.

Derzeit gibt es keine Möglichkeit, einen Benachrichtigungskanal automatisch zu verlängern. Wenn das Ablaufdatum eines Kanals näher rückt, 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 Kanals einen eindeutigen Wert verwenden. Beachten Sie, dass es wahrscheinlich einen Zeitraum gibt, in dem die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.

Benachrichtigungen erhalten

Jedes Mal, wenn sich eine beobachtete Ressource ändert, erhält Ihre Anwendung eine Benachrichtigung mit einer Beschreibung der Änderung. Die Directory API sendet diese Nachrichten als HTTPS-POST-Anfragen an die URL, die Sie als address-Property für diesen Benachrichtigungskanal angegeben haben.

Format der Benachrichtigungsnachrichten auswerten

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

Header

Benachrichtigungsnachrichten, die von der Directory API an Ihre Empfänger-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 mit jeder nachfolgenden Nachricht auf dem Kanal erhöht, sind aber nicht fortlaufend.
X-Goog-Resource-ID Ein intransparenter Wert, der die beobachtete Ressource identifiziert. Diese ID ist unabhängig von 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-Versions-spezifische Kennung für die beobachtete Ressource.
Manchmal vorhanden
X-Goog-Channel-Expiration Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in einem für Menschen lesbaren Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Benachrichtigungskanal-Token, das von Ihrer Anwendung festgelegt wurde und mit dem Sie die Benachrichtigungsquelle verifizieren können. Nur vorhanden, wenn definiert.

Benachrichtigungsnachrichten für Nutzer enthalten im Anfragetext die folgenden Informationen:

Attribut Beschreibung
kind Hiermit wird angegeben, dass es sich um eine Nutzerressource handelt. Wert: der feste String „admin#directory#user“.
id Die eindeutige Kennung der Nutzerressource.
etag ETag der Benachrichtigungsnachricht. Unterscheidet sich vom ETag der Nutzerressource.
primaryEmail Die primäre E-Mail-Adresse des Nutzers.

Beispiele

Benachrichtigungsnachrichten für User-Ressourcenereignisse 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: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Beispiel für einen von einem Nutzer gelöschten Termin:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

Auf Benachrichtigungen reagieren

Als 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, wird die Directory API mit exponentiellem Backoff noch einmal ausgeführt. Alle anderen Rückgabestatuscodes gelten als Fehler.

Benachrichtigungen deaktivieren

Mit der Property expiration wird festgelegt, wann die Benachrichtigungen automatisch beendet werden. Du kannst festlegen, dass du keine Benachrichtigungen mehr für einen bestimmten Kanal erhältst, bevor er abläuft. Rufe dazu die Methode stop unter dem folgenden URI auf:

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

Bei dieser Methode müssen Sie mindestens die id- und die resourceId-Properties des Kanals angeben, wie im Beispiel unten gezeigt. Wenn die Directory 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 desselben Clients (wie anhand der OAuth 2.0-Client-IDs aus den Authentifizierungstokens ermittelt) den Kanal beenden.
  • Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben Clients den Kanal beenden.

Im folgenden Codebeispiel wird gezeigt, wie Sie keine Benachrichtigungen mehr erhalten:

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

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