REST Resource: subscriptions

Zasób: 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 w przypadku zasobu docelowego określisz typ zdarzenia, który nie istnieje, żą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 przekazywać 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 żądaniach aktualizacji, aby zapewnić klientowi aktualną wartość przed kontynuacją.

Pole unii expiration. Data 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 zasobu, 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 za pomocą delegowania na całą domenę, możesz przedłużyć czas ważności subskrypcji do 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 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. 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. Zawsze wyświetlany na wyjściu, niezależnie od użytego na danych wejściowych.
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 do uwzględnienia w ładunku zdarzenia. Obsługiwane tylko w przypadku zdarzeń 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 utworzono wiadomość w Google Chat, 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 includeResource ma wartość true, lista pól do uwzględnienia w ładunku zdarzenia. Pola rozdzielaj 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 określisz pole, które nie istnieje w zasobie, system je zignoruje.

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 unii endpoint.

endpoint może być tylko jednym z tych elementów:
pubsubTopic

string

Stały. Temat Cloud Pub/Sub, który odbiera zdarzenia dla subskrypcji.

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 Google Cloud Pub/Sub Protocol Binding for CloudEvents (Google Cloud Pub/Sub Protocol Binding for 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 subskrypcji nie istnieje już.
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 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ółowe informacje o subskrypcji Google Workspace.

list

 Wyświetla listę subskrypcji Google Workspace.

patch

 aktualizuje lub odnawia subskrypcję Google Workspace.

reactivate

 Ponowne aktywowanie zawieszonej subskrypcji Google Workspace.