REST Resource: subscriptions

Zasób: subscription (subskrypcja)

Subskrypcja na otrzymywanie zdarzeń dotyczących zasobu Google Workspace. Aby dowiedzieć się więcej o subskrypcjach, przeczytaj omówienie interfejsu Google Workspace Events API.

Zapis JSON 
{
  "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.
}
Pola
name

string

Opcjonalnie: Stały. Identyfikator. Nazwa zasobu subskrypcji.

Format: subscriptions/{subscription}
uid

string

Tylko dane wyjściowe. Przypisany przez system unikalny identyfikator subskrypcji.
targetResource

string

Wymagane. Stały. Zasób Google Workspace monitorowany pod kątem zdarzeń w postaci pełnej nazwy zasobu. Więcej informacji na temat zasobów docelowych i obsługiwanych przez nie zdarzeń znajdziesz w artykule Obsługiwane zdarzenia Google Workspace.

Użytkownik może autoryzować Twoją aplikację tylko do utworzenia 1 subskrypcji dla danego zasobu docelowego. Jeśli aplikacja spróbuje utworzyć kolejną subskrypcję z tymi samymi danymi logowania użytkownika, żądanie zwróci błąd ALREADY_EXISTS.
eventTypes[]

string

Wymagane. Stały. Lista nieuporządkowana. Dane wejściowe tworzenia subskrypcji. W przeciwnym razie tylko dane wyjściowe. Co najmniej 1 typ zdarzenia dotyczącego zasobu docelowego, które chcesz otrzymać. Sformatowane zgodnie ze specyfikacją CloudEvents.

Obsługiwane typy zdarzeń zależą od zasobu docelowego subskrypcji. Szczegółowe informacje znajdziesz w artykule Obsługiwane zdarzenia Google Workspace.

Domyślnie otrzymujesz też zdarzenia dotyczące cyklu życia subskrypcji. W tym polu nie musisz określać zdarzeń cyklu życia.

Jeśli określisz typ zdarzenia, który nie istnieje w przypadku zasobu docelowego, żądanie zwróci kod stanu HTTP 400 Bad Request.
payloadOptions

object (PayloadOptions)

Opcjonalnie: Opcje dotyczące danych do uwzględnienia w ładunku zdarzenia. Obsługiwane tylko w przypadku wydarzeń w Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Wymagane. Stały. Punkt końcowy, w którym subskrypcja dostarcza zdarzenia, na przykład temat Pub/Sub.
state

enum (State)

Tylko dane wyjściowe. Stan subskrypcji. Określa, czy subskrypcja może otrzymywać zdarzenia i dostarczać je do punktu końcowego powiadomień.
suspensionReason

enum (ErrorType)

Tylko dane wyjściowe. Błąd, który spowodował zawieszenie subskrypcji.

Aby ponownie aktywować subskrypcję, napraw błąd i wywołaj metodę subscriptions.reactivate.
authority

string

Tylko dane wyjściowe. Użytkownik, który autoryzował utworzenie subskrypcji.

Format: users/{user}

W przypadku użytkowników Google Workspace wartością {user} jest pole user.id z interfejsu Directory API.
createTime

string (Timestamp format)

Tylko dane wyjściowe. Czas utworzenia subskrypcji.
updateTime

string (Timestamp format)

Tylko dane wyjściowe. Data ostatniej aktualizacji subskrypcji.
reconciling

boolean

Tylko dane wyjściowe. Jeśli true, subskrypcja jest aktualizowana.
etag

string

Opcjonalnie: Ta suma kontrolna jest obliczana przez serwer na podstawie wartości innych pól i może być wysyłana w razie żądań aktualizacji, aby mieć pewność, że wartość dla klienta jest aktualna, zanim przejdziesz dalej.

Pole sumy expiration. Czas wygaśnięcia subskrypcji.

Maksymalny czas wygaśnięcia zależy od tego, czy subskrypcja zawiera w ładunkach zdarzeń dane zasobów (określone w polu PayloadOptions):

  • Jeśli ładunki pomijają dane zasobów, może to potrwać do 7 dni.
  • Jeśli ładunki zawierają dane zasobów, do 4 godzin. Jeśli Twoja organizacja Google Workspace przyznaje dostęp do zasobu przez przekazywanie dostępu w całej domenie, możesz przedłużyć czas wygaśnięcia subskrypcji do maksymalnie 24 godzin.

Po wygaśnięciu subskrypcja jest automatycznie usuwana. Zdarzenia cyklu życia otrzymasz do notification_endpoint na 12 godzin i godzinę przed wygaśnięciem subskrypcji. Szczegółowe informacje znajdziesz w artykule Odbieranie zdarzeń cyklu życia i reagowanie na nie.

Aby zapobiec wygaśnięciu subskrypcji, możesz użyć metody UpdateSubscription, aby przedłużyć jej datę ważności. Więcej informacji znajdziesz w artykule Aktualizowanie i odnawianie subskrypcji. expiration może mieć tylko jedną z tych wartości:
expireTime

string (Timestamp format)

Pole domyślne niepuste. Sygnatura czasowa UTC wygaśnięcia subskrypcji. Zawsze wyświetlane na wyjściu, niezależnie od tego, co zostało użyte do wprowadzania danych.
ttl

string (Duration format)

Tylko dane wejściowe. Czas życia danych (TTL) lub czas trwania subskrypcji. Jeśli wartość nie jest określona lub ma wartość 0, używany jest maksymalny możliwy czas trwania.

PayloadOptions

Opcje dotyczące danych do uwzględnienia w ładunku zdarzenia. Obsługiwane tylko w przypadku wydarzeń w Google Chat.

Zapis JSON 
{
  "includeResource": boolean,
  "fieldMask": string
}
Pola
includeResource

boolean

Opcjonalnie: Określa, czy ładunek zdarzenia zawiera dane o zmienionym zasobie. Na przykład w przypadku zdarzenia, w którym została utworzona wiadomość w Google Chat, sprawdź, czy ładunek zawiera dane o zasobie Message. Jeśli zostanie ustawiona wartość false (fałsz), ładunek zdarzenia będzie zawierał tylko nazwę zmienionego zasobu.
fieldMask

string (FieldMask format)

Opcjonalnie: Jeśli includeResource ma wartość true, lista pól do uwzględnienia w ładunku zdarzenia. Oddziel pola przecinkami. Aby na przykład uwzględnić nadawcę wiadomości w Google Chat i godzinę utworzenia, wpisz message.sender,message.createTime. Jeśli go pominiesz, ładunek będzie zawierał wszystkie pola zasobu.

Jeśli podasz pole, które nie istnieje w przypadku zasobu, system zignoruje to pole.

NotificationEndpoint

Punkt końcowy, w którym subskrypcja dostarcza zdarzenia.

Zapis JSON 
{

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

Pole sumy endpoint.

endpoint może mieć tylko jedną z tych wartości:
pubsubTopic

string

Stały. Temat Cloud Pub/Sub, który odbiera zdarzenia związane z subskrypcją.

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

Musisz utworzyć temat w tym samym projekcie Google Cloud, w którym tworzysz tę subskrypcję.

Gdy temat otrzymuje zdarzenia, są one kodowane jako wiadomości Cloud Pub/Sub. Szczegółowe informacje znajdziesz w artykule Powiązanie protokołu Google Cloud Pub/Sub z CloudEvents.

Stan

Możliwe stany subskrypcji.

Wartości w polu enum
STATE_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
ACTIVE Subskrypcja jest aktywna i może odbierać oraz dostarczać zdarzenia do punktu końcowego powiadomień.
SUSPENDED Subskrypcja nie może odbierać zdarzeń z powodu błędu. Informacje o błędzie znajdziesz w polu suspensionReason.
DELETED Subskrypcja została usunięta.

ErrorType

Możliwe błędy dotyczące subskrypcji.

Wartości w polu enum
ERROR_TYPE_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
USER_SCOPE_REVOKED Autoryzowany użytkownik anulował przypisanie co najmniej 1 zakresu protokołu OAuth. Więcej informacji o autoryzacji w Google Workspace znajdziesz w artykule Konfigurowanie ekranu zgody OAuth.
RESOURCE_DELETED Zasób docelowy dla subskrypcji już nie istnieje.
USER_AUTHORIZATION_FAILURE Użytkownik, który autoryzował utworzenie subskrypcji, nie ma już dostępu do docelowego zasobu subskrypcji.
ENDPOINT_PERMISSION_DENIED Aplikacja Google Workspace nie ma uprawnień do dostarczania zdarzeń do punktu końcowego powiadomień Twojej subskrypcji.
ENDPOINT_NOT_FOUND Punkt końcowy powiadomień subskrypcji nie istnieje lub nie można znaleźć punktu końcowego w projekcie Google Cloud, w którym została utworzona subskrypcja.
ENDPOINT_RESOURCE_EXHAUSTED Punkt końcowy powiadomień subskrypcji nie odbierał zdarzeń z powodu niewystarczającego limitu lub osiągnięcia ograniczenia częstotliwości.
OTHER Wystąpił niezidentyfikowany błąd.

Metody

create

 Tworzy subskrypcję Google Workspace.

delete

 usuwa subskrypcję Google Workspace.

get

 Pobiera szczegółowe informacje o subskrypcji Google Workspace.

list

 Wyświetla listę subskrypcji Google Workspace.

patch

 Aktualizuje lub odnawia subskrypcję Google Workspace.

reactivate

 Ponownie aktywuje zawieszony abonament Google Workspace.