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 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-Attribut-String, der auf den Wert web_hook festgelegt ist.

• Ein address-Property-String, der auf die URL festgelegt ist, die auf Benachrichtigungen für diesen Benachrichtigungskanal wartet und darauf reagiert. Dies ist Ihre Webhook-Callback-URL und sie muss HTTPS verwenden.

  Die Admin SDK 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 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

  • Fügen Sie keine vertraulichen Daten wie OAuth-Tokens hinzu.

• 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 mit der watch-Anfrage ein Benachrichtigungskanal erstellt wurde, 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 finden Sie in den watch. für die Ressource Activities in der API-Referenz.

Synchronisierungsnachricht

Nachdem du einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt hast, sendet die Admin SDK 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 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 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.

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

Synchronisationsnachrichten haben immer den Wert 1 für den X-Goog-Message-Number-HTTP-Header. Jede weitere Benachrichtigung für diesen Kanal hat die größer als die vorherige ist, auch wenn die Meldung nicht fortlaufend sind.

Benachrichtigungskanäle verlängern

Ein Benachrichtigungskanal kann eine Ablaufzeit haben, mit einem Wert wird entweder durch Ihre Anfrage oder durch interne Limits der Admin SDK 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. 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. 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 die Property id des neuen Kanals einen eindeutigen Wert verwenden. Beachten Sie, dass es wahrscheinlich zu einer „Überschneidung“ kommt, wenn die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.

Nachrichtenformat für Benachrichtigungen interpretieren

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

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

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

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 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 spezifische Ereignisse:

• Admin
• calendar
• drive
• Gruppen
• login
• mobil
• saml
• Token
• user_accounts