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. Sie eliminieren zusätzliche Netzwerk- und Rechenleistung die Kosten für das Abfragen von Ressourcen, um festzustellen, ob sie sich geändert haben. Wenn sich eine beobachtete Ressource ändert, benachrichtigt die Directory API Ihr .

Damit Sie Push-Benachrichtigungen verwenden können, müssen Sie zwei Dinge tun:

  • Empfangs-URL oder Webhook einrichten des Rückrufempfängers.

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

  • Richten Sie einen (Benachrichtigungskanal) für jeden Ressourcenendpunkt ein, den Sie einrichten möchten. ansehen.

    Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Nachrichten. Im Rahmen der Kanaleinrichtung müssen Sie die URL angeben, unter der Sie Benachrichtigungen erhalten möchten. Wenn sich die Ressourcen eines Kanals ändern, Die Directory API sendet eine Benachrichtigung als POST an diese URL senden.

Derzeit unterstützt die Directory API Benachrichtigungen über Änderungen an Ressourcen vom Typ 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. Nach dem Festlegen der Benachrichtigungskanäle informiert die Directory API Ihre Anwendung, sobald eine überwachte Ressource Änderungen.

Wiedergabeanfragen stellen

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

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

So richten Sie einen Benachrichtigungskanal für Benachrichtigungen über Änderungen an einer bestimmten Ressource, senden Sie eine POST-Anfrage an den Die Methode watch für die Ressource.

Jeder Benachrichtigungskanal ist sowohl einem bestimmten Nutzer als auch eine bestimmte Ressource (oder eine Gruppe von Ressourcen) Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder Dienstkonto besitzt oder hat die Berechtigung, auf diese Ressource zuzugreifen.

Beispiele

Alle Überwachungsanfragen für die Ressource User für eine einzelne Domain haben das folgende allgemeine Format:

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 die 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.
  }
}

Verwenden Sie die Parameter customer und event, um die eindeutige ID des Google-Kontos des Kunden und den Ereignistyp anzugeben, für den Sie Benachrichtigungen erhalten möchten.

Folgende Werte sind für event möglich:

  • add: vom Nutzer erstelltes Ereignis
  • delete: Ereignis „Nutzer gelöscht“
  • makeAdmin: Ereignis zur Statusänderung des Nutzeradministratorstatus
  • undelete: Ereignis, dass ein Nutzer die Löschung rückgängig gemacht hat
  • 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 dieses Objekt eindeutig identifiziert in Ihrem Projekt zu erstellen. 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 Benachrichtigung die du für diesen Kanal erhältst.

  • Ein type-Attributstring, der auf den Wert festgelegt ist web_hook.

  • Einen address-Property-String, der auf die URL festgelegt ist, die überwacht und reagiert auf Benachrichtigungen für diesen Benachrichtigungskanal. 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 Thema nicht mit dem Ziel übereinstimmt Hostname.

Optionale Attribute

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

  • Ein token-Attribut, das einen beliebigen String angibt. -Wert zur Verwendung als Kanaltoken. 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 im X-Goog-Channel-Token-HTTP-Header in jeder Benachrichtigung Nachricht, die deine Anwendung für diesen Kanal erhält.

    Wenn Sie Benachrichtigungskanal-Tokens verwenden, empfehlen wir Folgendes:

    • Verwenden Sie ein erweiterbares Codierungsformat, z. B. URL-Suchanfrage. Parameter. Beispiel: forwardTo=hr&createdBy=mobile

    • Verwenden Sie keine sensiblen Daten wie OAuth-Tokens.

  • 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 Channel eine Ablaufzeit hat, wird dieser als Wert des HTTP-Headers X-Goog-Channel-Expiration (für Menschen lesbar) Format) in jeder Benachrichtigung, die Ihr Anwendung für diesen Kanal erhält.

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

Antwort auf Smartwatch

Wenn die watch-Anfrage erfolgreich eine Benachrichtigung erstellt wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Überwachungsantwort enthält Informationen über die den Sie gerade erstellt haben, 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 Sie im Rahmen Ihrer Anfrage gesendet haben, enthält der die zurückgegebenen Informationen auch die resourceId und resourceUri, um die dafür zu überwachende Ressource zu identifizieren Benachrichtigungskanal.

Sie können die zurückgegebenen Informationen an einen anderen Benachrichtigungskanal weitergeben. z. B. wenn Sie den Erhalt von E-Mails nicht mehr Benachrichtigungen.

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.

Du kannst die sync-Benachrichtigung ignorieren, aber du kannst verwenden. Wenn Sie z. B. entscheiden, Ihre des Kanals, können Sie X-Goog-Channel-ID und X-Goog-Resource-ID-Werte in einem Aufruf von keine Benachrichtigungen mehr 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

Synchronisierungsnachrichten haben immer das HTTP-Statuscode X-Goog-Message-Number Headerwert von 1. 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, mit einem Wert durch Ihre Anfrage oder interne Limits der Directory API bestimmt oder Standardwerte (der restriktivere Wert wird 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. Darüber hinaus enthält der Ablaufdatum und -uhrzeit werden (in visuell lesbarem Format) in jeder Benachrichtigung, die Ihre Anwendung für diesen Kanal in der HTTP-Header „X-Goog-Channel-Expiration“

Derzeit gibt es keine automatische Verlängerung eines Benachrichtigungskanals. Wann? ein Kanal bald abläuft, musst du ihn durch einen neuen ersetzen. Rufe dazu folgenden Link auf: die Methode watch. Wie immer müssen Sie für jedes Element einen eindeutigen Wert verwenden, Das Attribut id des neuen Channels Es gibt wahrscheinlich als „Überlappung“ Zeitraum, in dem die beiden Benachrichtigungskanäle für den Ressource aktiv sind.

Benachrichtigungen erhalten

Sobald 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 senden, die Sie als address-Property für diese Benachrichtigung Kanal.

Format der Benachrichtigungsnachrichten auswerten

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

Header

Benachrichtigungsnachrichten, die von der Directory API an Ihre Empfänger-URL gesendet werden, enthalten die folgenden HTTP-Header:

Header Beschreibung
Immer einblenden
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 lautet in allen API-Versionen stabil sein.
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 anwesend
X-Goog-Channel-Expiration Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals, angegeben in menschenlesbares Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Token des Benachrichtigungskanals, das von Ihrer Anwendung festgelegt wurde, und mit dem Sie die Benachrichtigungsquelle überprüfen können. Nur vorhanden, wenn definiert.

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

Attribut Beschreibung
kind Kennzeichnet dies als Nutzerressource. Wert: der feste String „admin#directory#user“.
id Die eindeutige Kennung der Nutzerressource.
etag ETag der Benachrichtigungsnachricht. Unterscheidet sich vom ETag der User-Ressource.
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 ein vom Nutzer gelöschtes Ereignis:

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

Bei erfolgreicher Ausführung 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. Jeder andere Rückgabestatuscode wird als Nachrichtenfehler betrachtet.

Benachrichtigungen deaktivieren

Mit der Eigenschaft expiration wird festgelegt, wann die Benachrichtigungen automatisch beendet werden. Sie können Du kannst festlegen, dass du für einen bestimmten Kanal keine Benachrichtigungen mehr erhalten möchtest, bevor dieser durch Aufrufen der Methode stop unter den folgenden URI:

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

Bei dieser Methode müssen Sie mindestens den Typ id- und resourceId-Eigenschaften, wie in den Beispiel unten. 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 kann der Client 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"
}