REST Resource: subscriptions

Zasób: subskrypcja

Subskrypcja otrzymywania zdarzeń dotyczących zasobu Google Workspace. Więcej informacji o subskrypcjach znajdziesz w artykule Omówienie interfejsu Google Workspace Event 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łe. Identyfikator. Nazwa zasobu subskrypcji.

Format: subscriptions/{subscription}
uid

string

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

string

To pole jest wymagane. Stałe. Zasób Google Workspace monitorowany pod kątem zdarzeń w postaci pełnej nazwy 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 autoryzować Twoją aplikację do utworzenia tylko jednej 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

To pole jest wymagane. Stałe. Lista nieuporządkowana. Pole do tworzenia subskrypcji. W przeciwnym razie tylko dane wyjściowe. Co najmniej 1 typ zdarzeń do otrzymywania dotyczących zasobu docelowego. Sformatowane zgodnie ze specyfikacją CloudEvents.

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

Domyślnie otrzymujesz też informacje o zdarzeniach związanych z cyklem życia subskrypcji. Nie musisz określać w tym polu zdarzeń cyklu życia.

Jeśli określisz typ zdarzenia, który nie istnieje dla 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)

To pole jest wymagane. Stałe. Punkt końcowy, w którym subskrypcja dostarcza zdarzenia, takie jak 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 powodujący zawieszenie subskrypcji.

Aby ponownie aktywować subskrypcję, rozwiąż 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ść {user} to pole user.id z interfejsu Directory API.
createTime

string (Timestamp format)

Tylko dane wyjściowe. Godzina 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 w trakcie aktualizowania.
etag

string

Opcjonalnie. Ta suma kontrolna jest obliczana przez serwer na podstawie wartości innych pól i może być wysyłana przy żądaniach aktualizacji w celu sprawdzenia, czy klient ma aktualną wartość, zanim przejdziesz dalej.

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

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

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

Po wygaśnięciu subskrypcji jest ona automatycznie usuwana. Zdarzenia cyklu życia są wysyłane do notification_endpoint na 12 godzin i 1 godzinę przed wygaśnięciem subskrypcji. Szczegółowe informacje znajdziesz w artykule Odbieranie zdarzeń cyklu życia i odpowiadanie na nie.

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

string (Timestamp format)

Wartość domyślna nie jest pusta. Sygnatura czasowa wygaśnięcia subskrypcji w strefie czasowej UTC. Zawsze wyświetlane na wyjściu, niezależnie od tego, jakie dane zostały użyte.
ttl

string (Duration format)

Tylko wejście. Czas życia danych (TTL) lub czas trwania subskrypcji. Jeśli wartość nie jest określona lub ustawiona na 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 ma 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. Jeśli na przykład chcesz uwzględnić nadawcę wiadomości w Google Chat i godzinę utworzenia, wpisz message.sender,message.createTime. Jeśli ten argument zostanie pominięty, ładunek będzie zawierał wszystkie pola dotyczące tego zasobu.

Jeśli określisz pole, które nie istnieje dla tego 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 być tylko jedną z tych wartości:
pubsubTopic

string

Stałe. Temat Cloud Pub/Sub, do którego wysyłane są zdarzenia subskrypcji.

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

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

Gdy temat odbiera zdarzenia, są one kodowane jako wiadomości Cloud Pub/Sub. Szczegółowe informacje znajdziesz w artykule Powiązanie protokołu Google Cloud Pub/Sub dla 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 swojego punktu końcowego powiadomień.
SUSPENDED Subskrypcja nie może odbierać zdarzeń z powodu błędu. Aby zidentyfikować błąd, zapoznaj się z polem 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 OAuth. Więcej informacji o autoryzacji w Google Workspace znajdziesz w artykule Konfigurowanie ekranu zgody OAuth.
RESOURCE_DELETED Docelowy zasób subskrypcji już nie istnieje.
USER_AUTHORIZATION_FAILURE Użytkownik, który autoryzował utworzenie subskrypcji, nie ma już dostępu do jej docelowego zasobu.
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 subskrypcja została utworzona.
ENDPOINT_RESOURCE_EXHAUSTED W punkcie końcowym powiadomienia subskrypcji nie odebrano zdarzeń z powodu niewystarczającego limitu lub osiągnięcia ograniczenia liczby żądań.
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

 Ponowne aktywowanie zawieszonego abonamentu Google Workspace.