Ta strona została przetłumaczona przez Cloud Translation API.

Subskrybowanie wydarzeń przy użyciu interfejsu Google Workspace Events API

Na tej stronie znajdziesz omówienie interfejsu Google Workspace Events API i dowiesz się, jak za jego pomocą subskrybować zdarzenia w Google Workspace.

Zdarzenia w Google Workspace przedstawiają zmiany w zasobach Google Workspace, takie jak ich utworzenie, aktualizacja lub usunięcie. Twoja aplikacja może zasubskrybować zasób Google Workspace, aby otrzymywać informacje o interesujących Cię wydarzeniach.

Jak aplikacja odbiera zdarzenia

Aby umożliwić aplikacji otrzymywanie zdarzeń Google Workspace, musisz utworzyć subskrypcje zasobów Google Workspace za pomocą interfejsu Google Workspace Events API.

Ilustracja przedstawiająca sposób, w jaki interfejs Google Workspace Events API dostarcza zdarzenia. — **Rysunek 1.** Przykład sposobu, w jaki interfejs Google Workspace Events API dostarcza zdarzenia do aplikacji Google Chat.

W poniższym przykładzie interfejs Google Workspace Events API dostarcza zdarzenia do aplikacji Google Chat w ramach subskrypcji:

Aplikacja do obsługi czatu subskrybuje pokój czatu.
Pokój czatu się zmieni. Np. w pokoju opublikowano nową wiadomość.
Google Chat przekazuje zdarzenie do tematu w Google Cloud Pub/Sub, który służy jako punkt końcowy powiadomienia subskrypcji. Zdarzenie zawiera dane o tym, co się zmieniło. Na przykład zdarzenie dotyczące nowej wiadomości zawiera szczegóły utworzonego zasobu Message.
Aplikacja Google Chat przetwarza wiadomość z Google Cloud Pub/Sub, która zawiera zdarzenie, i w razie potrzeby wykonuje działanie.

Ważna terminologia

Poniżej znajduje się lista popularnych terminów używanych w interfejsie Google Workspace Events API:

Wydarzenie Google Workspace

Zmiana zasobu Google Workspace. Zdarzenia są sformatowane za pomocą specyfikacji CloudEvents i mogą być zdarzeniami subskrypcji lub zdarzeniami cyklu życia:

Zdarzenie subskrypcji: Zmiana w zasobie Google Workspace, którą monitorujesz, np. nowa wiadomość w pokoju Google Chat. Możesz określić, ile szczegółów na temat zmienionego zasobu chcesz otrzymać. Szczegółowe informacje znajdziesz w artykule Struktura zdarzeń w Google Workspace.
Zdarzenie cyklu życia: Zdarzenie dotyczące Twojego abonamentu Google Workspace. Zdarzenia cyklu życia powiadamiają o problemach i stanie subskrypcji, dzięki czemu możesz uniknąć jej brakujących zdarzeń. Domyślnie subskrypcja zawsze odbiera zdarzenia cyklu życia. Szczegółowe informacje znajdziesz w artykule Zdarzenia cyklu życia subskrypcji Google Workspace.

Abonament Google Workspace

Nazwana encja, która monitoruje zasób z aplikacji Google Workspace. Subskrypcja jest reprezentowana przez zasób Subscription. Subskrypcja jest określana na podstawie tych informacji:

Zasób docelowy: Zasób Google Workspace, który chcesz monitorować. Ten zasób jest widoczny w polu targetResource subskrypcji Google Workspace. Każda subskrypcja może monitorować tylko 1 zasób. Informacje o tym, które zasoby Google Workspace obsługuje interfejs Google Workspace Events API, znajdziesz w artykule Obsługiwane zdarzenia w Google Workspace.
Typy zdarzeń: Typy zmian, o których chcesz otrzymywać powiadomienia dotyczące zasobu docelowego. Na przykład po zasubskrybowaniu pokoju Google Chat możesz wybrać, czy chcesz otrzymywać wydarzenia dotyczące tego pokoju i jego zasobów podrzędnych, takich jak subskrypcje i wiadomości.
Punkt końcowy powiadomienia: Punkt końcowy, w którym subskrypcja Google Workspace odbiera zdarzenia. Interfejs Google Workspace Events API obsługuje tematy Google Cloud Pub/Sub jako punkt końcowy powiadomień. Więcej informacji o korzystaniu z Google Cloud Pub/Sub znajdziesz w dokumentacji Google Cloud Pub/Sub.
Opcje ładunku: Dane o zdarzeniach, które chcesz otrzymywać dotyczące zmienionych zasobów.

Obsługiwane zdarzenia Google Workspace

Zdarzenia, które aplikacja może odbierać, zależą od zasobu docelowego subskrypcji. W tabeli poniżej znajdziesz obsługiwane zdarzenia w przypadku każdego możliwego zasobu docelowego.

Zasób docelowy	Format	Obsługiwane zdarzenia	Ograniczenia (jeśli mają zastosowanie)
Google Chat,
Pokoje Google Chat	Aby zasubskrybować konkretny pokój: `//chat.googleapis.com/spaces/SPACE_ID` Aby zasubskrybować wszystkie pokoje, do których należy ten użytkownik: `//chat.googleapis.com/spaces/-`	Wiadomości Wspieranie kanału Reakcje Miejsce Więcej informacji znajdziesz w artykule Subskrybowanie wydarzeń w Google Chat.	Użytkownik Google Chat, który autoryzuje subskrypcję, musi być użytkownikiem pokoju za pomocą swojego konta Google Workspace lub konta Google.
Użytkownicy Google Chat	`//cloudidentity.googleapis.com/users/USER_ID`	Wspieranie kanału Więcej informacji znajdziesz w artykule Subskrybowanie wydarzeń w Google Chat.	Subskrypcja otrzymuje tylko zdarzenia dotyczące użytkownika, który autoryzował subskrypcję. Użytkownik nie może autoryzować subskrypcji w imieniu innych użytkowników.
Google Meet
Sale konferencyjne w Google Meet	`//meet.googleapis.com/spaces/SPACE_ID`	Konferencje Sesje uczestników Nagrania Transkrypcje Szczegółowe informacje znajdziesz w artykule Subskrybowanie wydarzeń w Google Meet.
Użytkownicy Google Meet	`//cloudidentity.googleapis.com/users/USER_ID`	Konferencje Sesje uczestników Nagrania Transkrypcje Szczegółowe informacje znajdziesz w artykule Subskrybowanie wydarzeń w Google Meet.	Subskrypcja odbiera zdarzenia dotyczące sal konferencyjnych, w których użytkownik jest jednym z tych: Właściciel sali konferencyjnej. Organizator wydarzenia w Kalendarzu Google powiązanego z miejscem spotkania.

Struktura zdarzeń Google Workspace

Zdarzenia Google Workspace są zgodne ze specyfikacją CloudEvents, która jest standardowym sposobem opisywania danych zdarzeń. Zdarzenia Google Workspace obejmują:

Atrybuty CloudEvent.
Dane o zasobie Google Workspace, które zmienił się w wyniku zdarzenia

W tej sekcji omawiamy strukturę atrybutów i danych zdarzeń Google Workspace.

Atrybuty CloudEvent

Zdarzenia Google Workspace zawierają te wymagane atrybuty CloudEvents:

Atrybut	Opis	Przykład
`datacontenttype`	Typ danych przekazanych w zdarzeniu.	`application/json`
`id`	Identyfikator zdarzenia CloudEvent.	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	Źródło zdarzenia. W przypadku zdarzeń Google Workspace jest to pełna nazwa zasobu subskrypcji.	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	Wersja specyfikacji CloudEvents używana w przypadku tego zdarzenia.	`1.0`
`subject`	Zasób Google Workspace, w którym wystąpiło zdarzenie.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	Sygnatura czasowa momentu wystąpienia zdarzenia w formacie RFC 3339.	`2023-09-07T21:37:36.260127Z`
`type`	Typ zdarzenia w Google Workspace.	`google.workspace.chat.message.v1.created`

Dane zdarzenia

Dane zdarzenia to ładunek reprezentujący zmianę zasobu docelowego subskrypcji, w tym zasobów podrzędnych zasobu docelowego. W ramach subskrypcji możesz określić, czy ładunek ma zawierać dane o zmienionym zasobie czy tylko nazwę zmienionego zasobu.

Jeśli na przykład masz subskrypcję pokoju czatu, możesz otrzymywać informacje o nowych wiadomościach w tym pokoju. W przypadku zdarzeń dotyczących nowych wiadomości dane zdarzenia zawierają ładunek z utworzonym zasobem Google Chat spaces.message.

Podczas tworzenia subskrypcji możesz określić ilość danych dotyczących zasobów, które mają być uwzględniane w zdarzeniach odbieranych przez aplikację:

Uwzględnij dane zasobu: obejmuje niektóre lub wszystkie pola zmienionego zasobu. Jeśli zdecydujesz się uwzględnić dane zasobów, czas trwania subskrypcji będzie ograniczony do 4 godzin lub 24 godzin, jeśli korzystasz z przekazywania dostępu w całej domenie.
Wyklucz dane zasobu: zawiera tylko nazwę zmienionego zasobu. Czas trwania subskrypcji wynosi maksymalnie 7 dni. Aby uzyskać szczegółowe informacje o zdarzeniu, możesz utworzyć zapytanie dotyczące zasobu, korzystając z nazwy zasobu.

Te opcje danych zdarzeń znajdują się w polu payloadOptions subskrypcji.

Zdarzenia jako komunikaty Google Cloud Pub/Sub

Subskrypcje interfejsu Google Workspace Events API używają tematów Google Cloud Pub/Sub jako punktu końcowego powiadomień, który odbiera zdarzenia Google Workspace. Zdarzenia są kodowane jako wiadomości Google Cloud Pub/Sub. Aplikacja może przetworzyć wiadomość Google Cloud Pub/Sub, aby wykonać działanie lub odpowiedzieć na zdarzenie.

Poniższy przykład pokazuje wiadomość Google Cloud Pub/Sub, która zawiera zdarzenie dotyczące zaktualizowanej wiadomości w pokoju czatu:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

Zwróć uwagę na te pola:

attributes: atrybuty CloudEvent, które obejmują typ zdarzenia. W tym przypadku wydarzenie dotyczy zaktualizowanej wiadomości w pokoju.
data: dane zdarzenia ze szczegółowymi informacjami o zaktualizowanym zasobie spaces.message w formacie ciągu zakodowanego w Base64.
messageId: identyfikator wiadomości Google Cloud Pub/Sub.

Więcej informacji o określaniu zdarzeń CloudEvents w wiadomościach Google Cloud Pub/Sub znajdziesz w artykule [GA4] Powiązanie protokołu Google Cloud Pub/Sub dla CloudEvents.

Subskrybowanie wydarzeń w Google Chat
Zdarzenia cyklu życia w przypadku subskrypcji Google Workspace
Wybierz zakresy interfejsu Google Workspace Events API
Tworzenie subskrypcji Google Workspace