REST Resource: subscriptions

Ressource: Abo

Ein Abo, um Ereignisse zu einer Google Workspace-Ressource zu erhalten. Weitere Informationen zu Abos

JSON-Darstellung 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
Felder
name

string

Kennung. Ressourcenname des Abos.

Format: subscriptions/{subscription}
uid

string

Nur Ausgabe. Vom System zugewiesene eindeutige Kennung für das Abo.
targetResource

string

Erforderlich. Nicht veränderbar. Die Google Workspace-Ressource, die auf Ereignisse überwacht wird, formatiert als vollständiger Ressourcennamen. Informationen zu Zielressourcen und den von ihnen unterstützten Ereignissen finden Sie unter Unterstützte Google Workspace-Ereignisse.

Ein Nutzer kann Ihre App nur autorisieren, ein Abo für eine bestimmte Zielressource zu erstellen. Wenn Ihre App versucht, ein weiteres Abo mit denselben Nutzeranmeldedaten zu erstellen, gibt die Anfrage einen ALREADY_EXISTS-Fehler zurück.
eventTypes[]

string

Erforderlich. Unsortierte Liste. Eingabe zum Erstellen eines Abos. Andernfalls nur Ausgabe. Ein oder mehrere Ereignistypen, die für die Zielressource empfangen werden sollen. Gemäß der CloudEvents-Spezifikation formatiert.

Die unterstützten Ereignistypen hängen von der Zielressource Ihres Abos ab. Weitere Informationen finden Sie unter Unterstützte Google Workspace-Ereignisse.

Standardmäßig erhalten Sie auch Ereignisse zum Abo-Lebenszyklus. Sie müssen für dieses Feld keine Lebenszyklusereignisse angeben.

Wenn Sie einen Ereignistyp angeben, der für die Zielressource nicht vorhanden ist, wird für die Anfrage der HTTP-Statuscode 400 Bad Request zurückgegeben.
payloadOptions

object (PayloadOptions)

Optional. Optionen dazu, welche Daten in die Ereignisnutzlast aufgenommen werden sollen. Wird nur für Google Chat-Ereignisse unterstützt.
notificationEndpoint

object (NotificationEndpoint)

Erforderlich. Nicht veränderbar. Der Endpunkt, an den das Abo Ereignisse sendet, z. B. ein Pub/Sub-Thema.
state

enum (State)

Nur Ausgabe. Der Status des Abos. Gibt an, ob das Abo Ereignisse empfangen und an den Benachrichtigungs-Endpunkt senden kann.
suspensionReason

enum (ErrorType)

Nur Ausgabe. Der Fehler, der zur Sperrung des Abos geführt hat.

Um das Abo zu reaktivieren, beheben Sie den Fehler und rufen Sie die Methode subscriptions.reactivate auf.
authority

string

Nur Ausgabe. Der Nutzer, der die Erstellung des Abos autorisiert hat.

Format: users/{user}

Für Google Workspace-Nutzer ist der Wert {user} das Feld user.id aus der Directory API.
createTime

string (Timestamp format)

Nur Ausgabe. Der Zeitpunkt, zu dem das Abo erstellt wird.
updateTime

string (Timestamp format)

Nur Ausgabe. Der Zeitpunkt, zu dem das Abo zuletzt aktualisiert wurde.
reconciling

boolean

Nur Ausgabe. Wenn true, wird das Abo gerade aktualisiert.
etag

string

Optional. Diese Prüfsumme wird vom Server anhand des Werts anderer Felder berechnet und kann bei Aktualisierungsanfragen gesendet werden, um sicherzustellen, dass der Client vor dem Fortfahren einen aktuellen Wert hat.

Union-Feld expiration. Der Zeitpunkt, zu dem das Abo abläuft.

Die maximale Ablaufzeit hängt davon ab, ob Ihr Abo Ressourcendaten in Ereignis-Payloads enthält (angegeben im Feld PayloadOptions):

  • Wenn in den Nutzlasten Ressourcendaten fehlen, bis zu 7 Tage.
  • Wenn Nutzlasten Ressourcendaten enthalten, bis zu 4 Stunden. Wenn Ihre Google Workspace-Organisation über die domainweite Delegierung Zugriff auf die Ressource gewährt, können Sie die Ablaufzeit des Abos auf bis zu 24 Stunden verlängern.

Nach Ablauf eines Abos wird es automatisch gelöscht. Sie erhalten Lebenszyklusereignisse für notification_endpoint 12 Stunden und eine Stunde vor Ablauf des Abos. Weitere Informationen finden Sie unter Lebenszyklusereignisse empfangen und darauf reagieren.

Wenn Sie verhindern möchten, dass ein Abo abläuft, können Sie das Ablaufdatum mit der Methode UpdateSubscription verlängern. Weitere Informationen finden Sie unter Abo aktualisieren oder verlängern. Für expiration ist nur einer der folgenden Werte zulässig:
expireTime

string (Timestamp format)

Nicht leerer Standardwert. Der Zeitstempel in UTC, der angibt, wann das Abo abläuft. Wird immer bei der Ausgabe angezeigt, unabhängig davon, was bei der Eingabe verwendet wurde.
ttl

string (Duration format)

Nur Eingabe. Die Gültigkeitsdauer (TTL) des Abos. Wenn nicht angegeben oder auf 0 festgelegt, wird die maximal mögliche Dauer verwendet.

PayloadOptions

Optionen dazu, welche Daten in die Ereignisnutzlast aufgenommen werden sollen. Wird nur für Google Chat-Ereignisse unterstützt.

JSON-Darstellung 
{
  "includeResource": boolean,
  "fieldMask": string
}
Felder
includeResource

boolean

Optional. Gibt an, ob die Ereignisnutzlast Daten zur geänderten Ressource enthält. Beispiel: Bei einem Ereignis, bei dem eine Google Chat-Nachricht erstellt wurde, enthält die Nutzlast Daten zur Message-Ressource. Bei „false“ enthält die Ereignisnutzlast nur den Namen der geänderten Ressource.
fieldMask

string (FieldMask format)

Optional. Wenn includeResource auf true festgelegt ist, die Liste der Felder, die in die Ereignisnutzlast aufgenommen werden sollen. Trennen Sie die Felder durch ein Komma. Wenn Sie beispielsweise den Absender und die Erstellungszeit einer Google Chat-Nachricht einfügen möchten, geben Sie message.sender,message.createTime ein. Wenn nichts angegeben ist, enthält die Nutzlast alle Felder für die Ressource.

Wenn Sie ein Feld angeben, das für die Ressource nicht vorhanden ist, wird es vom System ignoriert.

NotificationEndpoint

Der Endpunkt, an den Ereignisse für das Abo gesendet werden.

JSON-Darstellung 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
Felder

Union-Feld endpoint.

Für endpoint ist nur einer der folgenden Werte zulässig:
pubsubTopic

string

Nicht veränderbar. Das Pub/Sub-Thema, das Ereignisse für das Abo empfängt.

Format: projects/{project}/topics/{topic}

Sie müssen das Thema im selben Google Cloud-Projekt erstellen, in dem Sie dieses Abo erstellen.

Hinweis: In der Google Workspace Events API werden Sortierschlüssel für sequenzielle Ereignisse verwendet. Wenn für das Cloud Pub/Sub-Thema eine Richtlinie zum Speichern von Nachrichten konfiguriert ist, die die nächstgelegene Google Cloud-Region ausschließt, schlägt das Veröffentlichen von Ereignissen mit Reihenfolgeschlüsseln fehl.

Wenn das Thema Ereignisse empfängt, werden die Ereignisse als Pub/Sub-Nachrichten codiert. Weitere Informationen finden Sie unter Google Cloud Pub/Sub Protocol Binding for CloudEvents.

Status

Mögliche Status für das Abo.

Enums
STATE_UNSPECIFIED Standardwert Dieser Wert wird nicht verwendet.
ACTIVE Das Abo ist aktiv und kann Ereignisse an seinen Benachrichtigungs-Endpunkt senden und von dort empfangen.
SUSPENDED Das Abo kann aufgrund eines Fehlers keine Ereignisse empfangen. Informationen zum Identifizieren des Fehlers finden Sie im Feld suspensionReason.
DELETED Das Abo wird gelöscht.

ErrorType

Mögliche Fehler bei einem Abo.

Enums
ERROR_TYPE_UNSPECIFIED Standardwert Dieser Wert wird nicht verwendet.
USER_SCOPE_REVOKED Der autorisierende Nutzer hat die Erteilung von einem oder mehreren OAuth-Bereichen widerrufen. Weitere Informationen zur Autorisierung für Google Workspace finden Sie unter OAuth-Zustimmungsbildschirm konfigurieren.
RESOURCE_DELETED Die Zielressource für das Abo ist nicht mehr vorhanden.
USER_AUTHORIZATION_FAILURE Der Nutzer, der die Erstellung des Abos autorisiert hat, hat keinen Zugriff mehr auf die Zielressource des Abos.
ENDPOINT_PERMISSION_DENIED Die Google Workspace-Anwendung hat keinen Zugriff, um Ereignisse an den Benachrichtigungsendpunkt Ihres Abos zu senden.
ENDPOINT_NOT_FOUND Der Benachrichtigungsendpunkt des Abos ist nicht vorhanden oder kann im Google Cloud-Projekt, in dem Sie das Abo erstellt haben, nicht gefunden werden.
ENDPOINT_RESOURCE_EXHAUSTED Der Benachrichtigungsendpunkt des Abos konnte aufgrund eines unzureichenden Kontingents oder einer Ratenbegrenzung keine Ereignisse empfangen.
OTHER Ein unbekannter Fehler ist aufgetreten.

Methoden

create

 Erstellt ein Google Workspace-Abo.

delete

 Löscht ein Google Workspace-Abo.

get

 Ruft Details zu einem Google Workspace-Abo ab.

list

 Listet Google Workspace-Abos auf.

patch

 Aktualisiert oder verlängert ein Google Workspace-Abo.

reactivate

 Reaktiviert ein gesperrtes Google Workspace-Abo.