Push-Benachrichtigungen

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 überwacht und darauf reagiert. Dies ist Ihre Webhook-Callback-URL und 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 Inhaber nicht mit dem Zielhostnamen übereinstimmt.

Optionale Attribute

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

• Eine token-Eigenschaft, 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 überprüfen, ob alle eingehenden Nachrichten zu einem Kanal gehören, den Ihre Anwendung erstellt hat, um sicherzustellen, dass die Benachrichtigung nicht gefälscht wird, oder um die Nachricht basierend auf diesem Kanal an das richtige Ziel innerhalb Ihrer Anwendung weiterzuleiten. Maximale Länge: 256 Zeichen.

  Das Token ist in jedem X-Goog-Channel-Token-HTTP-Header 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

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

• Ein expiration-Attributstring, der auf einen Unix-Zeitstempel (in Millisekunden) des Datums und der Uhrzeit festgelegt ist, ab dem die Admin SDK 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.

Antwort auf Smartwatch

Wenn die watch-Anfrage erfolgreich einen Benachrichtigungskanal erstellt, wird der HTTP-Statuscode 200 OK zurückgegeben.

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

{
  "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 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 Vorgänge des Benachrichtigungskanals ü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 Aktivitäten.

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 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 du beispielsweise den Kanal nicht behalten möchtest, kannst du die Werte X-Goog-Channel-ID und X-Goog-Resource-ID in einem Aufruf 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 Admin SDK 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. Der Wert wird entweder durch Ihre Anfrage oder durch interne Limits oder Standardwerte der Admin SDK API bestimmt. Dabei wird der restriktivere 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. Darüber hinaus ist das Ablaufdatum und die Ablaufzeit (in visuell lesbarem Format) in jeder Benachrichtigungsnachricht enthalten, die Ihre Anwendung für diesen Kanal im HTTP-Header X-Goog-Channel-Expiration erhält.

Derzeit gibt es keine Möglichkeit, einen Benachrichtigungskanal automatisch zu verlängern. Wenn ein Kanal kurz vor seinem Ablauf steht, müssen Sie ihn durch einen neuen ersetzen. Rufen Sie dazu die Methode watch auf. 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 der Dienst die API-Clientbibliothek von Google verwendet und 500,502, 503 oder 504 zurückgibt, versucht die Admin SDK API, diese mit einem exponentiellen Backoff zu wiederholen. Alle anderen Rückgabestatuscodes gelten als Fehler.

Benachrichtigungsereignisse der Admin SDK API

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

Push-Benachrichtigungen der Reports API enthalten zwei Arten von Nachrichten: Synchronisierungsnachrichten und Ereignisbenachrichtigungen. Der Nachrichtentyp wird im X-Goog-Resource-State-HTTP-Header 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
• groups
• login
• mobil
• saml
• token
• user_accounts