Push-Benachrichtigungen

Erforderliche Properties

Bei jeder watch-Anfrage müssen die folgenden Felder angegeben werden:

• Ein id-Attributstring, der dieses Objekt eindeutig identifiziert in Ihrem Projekt zu erstellen. Wir empfehlen die Verwendung von eine universell eindeutige Kennung (UUID) oder Ähnliches eindeutigen String hinzu. 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 muss HTTPS verwenden.

  Die Admin SDK API kann Benachrichtigungen an diese HTTPS-Adresse nur verwenden, wenn ein gültiges SSL-Zertifikat installiert ist auf Ihrem Webserver. 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 diese optionalen Felder auch mit Ihrem watch-Anfrage:

• Ein token-Attribut, das einen beliebigen String angibt. -Wert zur Verwendung als Kanaltoken. Du kannst den Benachrichtigungskanal verwenden für verschiedene Zwecke. Sie können beispielsweise die Methode um zu überprüfen, ob alle eingehenden Nachrichten zu einem Kanal gehören, Anwendung erstellt, um sicherzustellen, dass die Benachrichtigung nicht um Spoofing zu verhindern, oder die Nachricht an das richtige Ziel innerhalb entsprechend dem Zweck dieses Kanals anpassen. 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 Tokens für Benachrichtigungskanäle 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-Attributstring, der auf einen Unix-Zeitstempel (in Millisekunden) für das Datum und die Uhrzeit, zu der die Admin SDK API keine weiteren Nachrichten mehr für diesen Benachrichtigungskanal senden.

  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.

Antwort ansehen

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": "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 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 den watch. für die Ressource Activities in der API-Referenz.

Nachricht synchronisieren

Nachdem Sie einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt haben, zeigt der Die Admin SDK API sendet eine sync-Nachricht, um anzugeben, dass Benachrichtigungen werden gestartet. Das X-Goog-Resource-State-HTTP Der Headerwert für diese Nachrichten ist sync. Aufgrund des Netzwerks Probleme mit dem Zeitplan haben, ist es möglich, dass die sync-Nachricht noch bevor Sie die Antwort der Methode watch 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 auch die sync-Benachrichtigung an, eine Initialisierung durchzuführen, um sich auf späteren Terminen.

Das Format der sync-Nachrichten, an die die Admin SDK API sendet Ihre Empfangs-URL 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 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 weitere Benachrichtigung für diesen Kanal hat die größer als die vorherige ist, auch wenn die Meldung keine fortlaufende Nummerierung.

Benachrichtigungskanäle verlängern

Ein Benachrichtigungskanal kann eine Ablaufzeit haben, mit einem Wert der entweder durch Ihre Anfrage oder durch interne Limits der Admin SDK API bestimmt wird oder Standardwerte (der restriktivere Wert wird verwendet). Ablauf des Kanals (sofern vorhanden) als Unix-Zeitstempel (in Millisekunden) in den Informationen, die von der Methode watch zurückgegeben werden. Darüber hinaus enthält der Ablaufdatum und -uhrzeit werden (in visuell lesbarem Format) in jedem 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.

Nachrichtenformat für Benachrichtigungen interpretieren

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

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

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

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

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 gibt 500,502, 503 oder 504, die Admin SDK API, zurück. Wiederholungsversuche mit exponentiellem Backoff. Jeder andere Rückgabestatuscode wird als Nachrichtenfehler betrachtet.

Informationen zu Admin SDK API-Benachrichtigungsereignissen

Dieser Abschnitt enthält Details zu den Benachrichtigungen, die Sie erhalten, wenn Push-Benachrichtigungen mit der Admin SDK API verwendet werden.

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

• Admin
• kalender
• Fahren
• Gruppen
• login
• mobil
• saml
• Token
• user_accounts