REST Resource: subscriptions

Zasób: Subscription

Subskrypcja umożliwiająca otrzymywanie zdarzeń dotyczących zasobu Google Workspace. Więcej informacji o subskrypcjach znajdziesz w omówieniu 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

Identyfikator. Nazwa zasobu subskrypcji.

Format: subscriptions/{subscription}
uid

string

Tylko dane wyjściowe. Unikalny identyfikator subskrypcji przypisany przez system.
targetResource

string

Wymagane. Niezmienne. Zasób Google Workspace, który jest monitorowany pod kątem zdarzeń, sformatowany jako pełna nazwa zasobu. Więcej informacji o zasobach docelowych i obsługiwanych przez nie zdarzeniach znajdziesz w artykule Obsługiwane zdarzenia Google Workspace.

Użytkownik może zezwolić aplikacji na utworzenie tylko 1 subskrypcji dla danego zasobu docelowego. Jeśli aplikacja spróbuje utworzyć kolejną subskrypcję przy użyciu tych samych danych logowania użytkownika, żądanie zwróci błąd ALREADY_EXISTS.
eventTypes[]

string

Wymagane. Lista nieuporządkowana. Dane wejściowe do utworzenia subskrypcji. W przeciwnym razie tylko dane wyjściowe. Co najmniej jeden typ zdarzeń, które mają być odbierane w związku z zasobem docelowym. Sformatowane zgodnie ze specyfikacją CloudEvents.

Obsługiwane typy zdarzeń zależą od zasobu docelowego subskrypcji. Więcej informacji znajdziesz w artykule Obsługiwane wydarzenia w Google Workspace.

Domyślnie otrzymujesz też zdarzenia dotyczące cyklu życia subskrypcji. W przypadku tego pola 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, które mają być uwzględnione w ładunku zdarzenia. Obsługiwane tylko w przypadku wydarzeń w Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Wymagane. Niezmienne. Punkt końcowy, do którego subskrypcja dostarcza zdarzenia, np. temat Pub/Sub.
state

enum (State)

Tylko dane wyjściowe. Stan subskrypcji. Określa, czy subskrypcja może odbierać 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ę, rozwiąż problem 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ść {user} to 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. Ostatnia aktualizacja subskrypcji.
reconciling

boolean

Tylko dane wyjściowe. Jeśli true, subskrypcja jest w trakcie aktualizacji.
etag

string

Opcjonalnie. Suma kontrolna jest obliczana przez serwer na podstawie wartości innych pól i może być wysyłana w żądaniach aktualizacji, aby mieć pewność, że klient ma aktualną wartość przed kontynuowaniem.

Pole unii expiration. Data wygaśnięcia subskrypcji.

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

  • Jeśli ładunki nie zawierają danych o zasobach, maksymalnie 7 dni.
  • Jeśli ładunki zawierają dane o zasobach, maksymalnie 4 godziny. Jeśli Twoja organizacja Google Workspace przyznaje dostęp do zasobu za pomocą delegowania w całej domenie, możesz przedłużyć czas wygaśnięcia subskrypcji do 24 godzin.

Po wygaśnięciu subskrypcja jest automatycznie usuwana. Otrzymasz zdarzenia cyklu życia notification_endpoint 12 godzin i godzinę przed wygaśnięciem subskrypcji. Więcej informacji znajdziesz w artykule Otrzymywanie zdarzeń cyklu życia i odpowiadanie na nie.

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

string (Timestamp format)

Wartość domyślna nie może być pusta. Sygnatura czasowa UTC wskazująca, kiedy subskrypcja wygasa. Jest zawsze wyświetlana na wyjściu niezależnie od tego, co zostało użyte na wejściu.
ttl

string (Duration format)

Tylko dane wejściowe. Czas życia (TTL) lub okres subskrypcji. Jeśli wartość nie zostanie podana lub będzie ustawiona na 0, używany będzie maksymalny możliwy czas trwania.

PayloadOptions

Opcje dotyczące danych, które mają być uwzględnione 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 zasobie, który uległ zmianie. Na przykład w przypadku zdarzenia, w którym utworzono wiadomość w Google Chat, informuje, czy ładunek zawiera dane o zasobie Message. Jeśli wartość to „false”, ładunek zdarzenia zawiera tylko nazwę zmienionego zasobu.
fieldMask

string (FieldMask format)

Opcjonalnie. Jeśli parametr includeResource ma wartość true, lista pól do uwzględnienia w ładunku zdarzenia. Pola rozdziel przecinkami. Aby na przykład uwzględnić nadawcę i czas utworzenia wiadomości w Google Chat, wpisz message.sender,message.createTime. Jeśli zostanie pominięty, ładunek będzie zawierać wszystkie pola zasobu.

Jeśli określisz pole, które nie istnieje w przypadku zasobu, system je zignoruje.

NotificationEndpoint

Punkt końcowy, do którego 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 unii endpoint.

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

string

Niezmienne. Temat Pub/Sub, który odbiera zdarzenia dotyczące subskrypcji.

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

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

Uwaga: interfejs Google Workspace Events API używa kluczy kolejności na potrzeby zdarzeń sekwencyjnych. Jeśli temat Cloud Pub/Sub ma skonfigurowaną zasadę przechowywania wiadomości, która wyklucza najbliższy region Google Cloud, publikowanie zdarzeń z kluczami kolejności zakończy się niepowodzeniem.

Gdy temat otrzyma zdarzenia, są one kodowane jako wiadomości Pub/Sub. Szczegółowe informacje znajdziesz w artykule Google Cloud Pub/Sub Protocol Binding for CloudEvents (Powiązanie protokołu Google Cloud Pub/Sub ze zdarzeniami w chmurze).

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. Aby zidentyfikować błąd, sprawdź pole suspensionReason.
DELETED Subskrypcja zostanie usunięta.

ErrorType

Możliwe błędy subskrypcji.

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

Metody

create

 Tworzy subskrypcję Google Workspace.

delete

 Usuwa subskrypcję Google Workspace.

get

 Pobiera szczegóły subskrypcji Google Workspace.

list

 Wyświetla listę subskrypcji Google Workspace.

patch

 Aktualizuje lub odnawia subskrypcję Google Workspace.

reactivate

 Ponownie aktywuje zawieszony abonament Google Workspace.