REST Resource: subscriptions

Zasób: subscription (subskrypcja)

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

Identyfikator. Nazwa zasobu subskrypcji.

Format: subscriptions/{subscription}
uid

string

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

string

Wymagane. Niezmienna. Zasób Google Workspace monitorowany pod kątem zdarzeń w postaci pełnej nazwy zasobu. Więcej informacji o zasobach docelowych i zdarzeniach, które obsługują, 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ę przy użyciu tych samych danych uwierzytelniających, żądanie zwróci błąd ALREADY_EXISTS.
eventTypes[]

string

Wymagane. Lista nieuporządkowana. Dane potrzebne do utworzenia subskrypcji. W przeciwnym razie tylko dane wyjściowe. Co najmniej 1 typ zdarzenia, które ma być otrzymywane na temat zasobu docelowego. sformatowany zgodnie ze specyfikacją CloudEvents.

Obsługiwane typy zdarzeń zależą od zasobu docelowego w subskrypcji. Więcej informacji 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, które mają być uwzględnione w ładunku zdarzenia. Obsługiwane tylko w przypadku zdarzeń Google Chat.
notificationEndpoint

object (NotificationEndpoint)

Wymagane. Niezmienna. Punkt końcowy, w którym 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ę, 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 unii expiration. Data wygaśnięcia subskrypcji.

Maksymalny czas ważności zależy od tego, czy Twoja subskrypcja zawiera dane zasobów w danych zdarzenia (określone w polu PayloadOptions):

  • Jeśli ładunki pomijają dane zasobów, może to potrwać do 7 dni.
  • Jeśli dane payload 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 są wysyłane do notification_endpoint 12 godzin i 1 godzinę przed wygaśnięciem subskrypcji. Szczegółowe informacje znajdziesz w artykule Otrzymywanie i odpowiadanie na zdarzenia cyklu życia.

Aby zapobiec wygaśnięciu subskrypcji, możesz użyć metody UpdateSubscription, aby przedłużyć jej datę ważności. Szczegółowe informacje znajdziesz w artykule Aktualizowanie i odnawianie subskrypcji. expiration może być tylko jednym z tych elementów:
expireTime

string (Timestamp format)

Domyślna wartość niepusta. Sygnatura czasowa UTC daty wygaśnięcia subskrypcji. 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 danych (TTL) lub czas trwania subskrypcji. Jeśli nie zostanie podany lub zostanie ustawiony na 0, zostanie użyty 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 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 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 rozdzielaj przecinkami. Aby na przykład uwzględnić nadawcę i czas utworzenia wiadomości w Google Chat, wpisz message.sender,message.createTime. Jeśli nazwa zostanie pominięta, ładunek będzie zawierał wszystkie pola zasobu.

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

NotificationEndpoint

Punkt końcowy, do którego subskrypcja wysyła 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

Niezmienna. 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ć zdarzenia oraz przesyłać je 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 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 zatwierdził 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 znaleźć punktu końcowego w projekcie Google Cloud, w którym została utworzona subskrypcja.
ENDPOINT_RESOURCE_EXHAUSTED Punkt końcowy powiadomień subskrypcji nie otrzymał zdarzeń z powodu niewystarczającego limitu lub osiągnięcia limitu liczby żądań.
OTHER Wystąpił nieokreślony błąd.

Metody

create

 Tworzy subskrypcję Google Workspace.

delete

 Usuwa subskrypcję Google Workspace.

get

 Pobiera szczegóły subskrypcji Google Workspace.

list

 Wyświetla subskrypcje Google Workspace.

patch

 aktualizuje lub odnawia subskrypcję Google Workspace.

reactivate

 Ponownie aktywuje zawieszony abonament Google Workspace.