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 Event API oraz informacje o tym, jak go używać do subskrybowania zdarzeń w Google Workspace.

Zdarzenia Google Workspace odzwierciedlają zmiany w zasobach Google Workspace, na przykład czas ich tworzenia, aktualizacji lub usuwania. Twoja aplikacja może zasubskrybować zasoby Google Workspace, aby otrzymywać interesujące Cię wydarzenia.

Jak aplikacja odbiera zdarzenia

Aby umożliwić swojej aplikacji odbieranie zdarzeń Google Workspace, możesz utworzyć subskrypcje zasobów Google Workspace za pomocą interfejsu Google Workspace Event API.

Ilustracja pokazująca, jak interfejs Google Workspace Event API dostarcza zdarzenia.

Interfejs Google Workspace Event API dostarcza zdarzenia do aplikacji za pomocą subskrypcji:

Aplikacja subskrybuje zasób w aplikacji Google Workspace, np. pokój Google Chat.
Zasób, do którego masz subskrypcję zmian.
Aplikacja Google Workspace wysyła zdarzenie do tematu w Google Cloud Pub/Sub, który służy jako punkt końcowy powiadomień w Twojej subskrypcji Google Workspace. Zawiera ono dane o tym, co się zmieniło w zasobie.
Aplikacja przetwarza wiadomość Google Cloud Pub/Sub, która zawiera zdarzenie, i w razie potrzeby podejmuje odpowiednie działania.

Ważne terminy

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

Wydarzenie Google Workspace

Zmiana w zasobie Google Workspace. Zdarzenia są formatowane za pomocą specyfikacji CloudEvents i mogą być zdarzeniem subskrypcji lub zdarzeniem cyklu życia:

Zdarzenie subskrypcji: Zmiana zasobu Google Workspace, który monitorujesz, na przykład nowa wiadomość w pokoju Google Chat. Możesz określić, ile szczegółów chcesz otrzymywać na temat zmienionego zasobu. Więcej informacji znajdziesz w artykule Struktura zdarzeń Google Workspace.
Zdarzenie cyklu życia: Zdarzenie dotyczące Twojej subskrypcji Google Workspace. Zdarzenia cyklu życia informują o problemach i stanie subskrypcji, dzięki czemu możesz ich uniknąć. Domyślnie subskrypcja zawsze otrzymuje zdarzenia cyklu życia. Szczegółowe informacje znajdziesz w artykule Zdarzenia cyklu życia dla 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 reprezentowany 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 Event API, znajdziesz w sekcji Obsługiwane zdarzenia Google Workspace.
Typy zdarzeń: Typy zmian, o których chcesz otrzymywać powiadomienia dotyczące zasobu docelowego. Jeśli na przykład subskrybujesz pokój w Google Chat, możesz wybrać, czy chcesz otrzymywać informacje o wydarzeniach dotyczących 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 Event 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 zdarzenia, które chcesz otrzymywać na temat 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 dla każdego możliwego zasobu docelowego.

Zasób docelowy	Format	Obsługiwane zdarzenia	Ograniczenia (w odpowiednich przypadkach)
Google Chat,
Pokoje Google Chat	`//chat.googleapis.com/spaces/SPACE_ID`	Wiadomości Wspieranie kanału Reakcje Miejsce Więcej informacji znajdziesz w artykule Subskrybowanie wydarzeń w Google Chat.	Użytkownik Google Chat, który autoryzował 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 odbiera tylko zdarzenia dotyczące użytkownika, który ją autoryzował. 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ń 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ń Google Meet.	Subskrypcja otrzymuje zdarzenia dotyczące sal konferencyjnych, w których użytkownik jest jednym z tych typów: Właściciel sali konferencyjnej. Organizator wydarzenia w Kalendarzu Google powiązanego z miejscem spotkań.

Struktura zdarzeń Google Workspace

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

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

W tej sekcji opisujemy 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, które zostały przekazane 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, która jest 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 wystąpienia zdarzenia w formacie RFC 3339.	`2023-09-07T21:37:36.260127Z`
`type`	Typ zdarzenia Google Workspace.	`google.workspace.chat.message.v1.created`

Dane zdarzenia

Dane zdarzenia to ładunek, który reprezentuje zmianę docelowego zasobu subskrypcji, w tym zasobów podrzędnych zasobu docelowego. W 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ć zdarzenia dotyczące nowych wiadomości w tym pokoju. W przypadku zdarzeń dotyczących nowych wiadomości dane zdarzenia zawierają ładunek z utworzonym zasobem spaces.message Google Chat.

Podczas tworzenia subskrypcji możesz określić, ile danych zasobów ma obejmować zdarzenia odbierane przez aplikację:

Uwzględnij dane zasobów: zawiera niektóre lub wszystkie pola zmienionego zasobu. Jeśli zdecydujesz się uwzględnić dane o zasobach, okres subskrypcji jest ograniczony do 4 godzin lub 24 godzin, jeśli używasz przekazywania dostępu w całej domenie.
Wyklucz dane zasobów: zawiera tylko nazwę zmienionego zasobu. Twoja subskrypcja może trwać maksymalnie 7 dni. Aby uzyskać szczegóły zdarzenia, możesz wysłać zapytanie do zasobu, podając jego nazwę.

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

Zdarzenia jako wiadomości Google Cloud Pub/Sub

Subskrypcje Google Workspace Event 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. Twoja 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 zdarzenie dotyczy zaktualizowanej wiadomości w pokoju.
data: dane zdarzenia ze szczegółami zaktualizowanego zasobu spaces.message w postaci ciągu zakodowanego w formacie 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 Powiązanie protokołu Google Cloud Pub/Sub z CloudEvents.

Subskrybowanie wydarzeń w Google Chat
Zdarzenia cyklu życia dotyczące subskrypcji Google Workspace
Wybieranie zakresów interfejsu Google Workspace Event API
Tworzenie subskrypcji Google Workspace