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 możesz używać interfejsu API do subskrybowania zdarzeń w Google Workspace.

Zdarzenia Google Workspace reprezentują zmiany w zasobach Google Workspace, na przykład gdy zasoby są tworzone, aktualizowane lub usuwane. Aplikacja może subskrybować do zasobu Google Workspace, aby otrzymywać informacje o wydarzeniach co może Cię zainteresować.

Jak aplikacja odbiera zdarzenia

Aby aplikacja mogła otrzymywać zdarzenia Google Workspace, musisz użyć Interfejs Google Workspace Events API do tworzenia subskrypcji Google Workspace i zasobami Google Cloud.

Ilustracja przedstawiająca sposób, w jaki interfejs Google Workspace Events API dostarcza zdarzenia.
Rysunek 1. Przykład tego, jak funkcja Interfejs Google Workspace Events API dostarcza zdarzenia do aplikację Google Chat.

W przykładzie poniżej przedstawiliśmy sposób, w jaki interfejs Google Workspace Events API zapewnia zdarzeń w aplikacji Google Chat w ramach subskrypcji:

  1. Aplikacja do obsługi czatu subskrybuje pokój czatu.
  2. Zmienia się pokój czatu. Na przykład została opublikowana nowa wiadomość w przestrzeni kosmicznej.
  3. Google Chat przedstawia zdarzenie na temat w rozmowie Google Cloud Pub/Sub, który służy jako punkt końcowy powiadomień dla subskrypcji. Wydarzenie zawiera dane o tym, co się zmieniło. Na przykład, gdy wybierzesz wydarzenie dotyczące wydarzenie zawiera szczegółowe informacje o zasobie Message, który jest Utworzono.
  4. Aplikacja Google Chat przetwarza Google Cloud Wiadomość 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 Interfejs Google Workspace Events API:

Wydarzenie Google Workspace

Zmiana zasobu Google Workspace. Zdarzenia są formatowane za pomocą tagów CloudEvents i może być zdarzeniem subskrypcji lub zdarzenie cyklu życia:

Zdarzenie subskrypcji
zmianę w zasobie Google Workspace, który monitorujesz; np. nowej wiadomości w pokoju Google Chat. Możesz określić, ile szczegółowe informacje o zmienionym zasobie, które chcesz otrzymać. Więcej informacji: Struktura zdarzeń Google Workspace.
Zdarzenie cyklu życia
Zdarzenie dotyczące Twojego abonamentu Google Workspace. Zdarzenia cyklu życia powiadamia Cię o problemach i stanie subskrypcji, aby umożliwić Ci aby uniknąć brakujących zdarzeń subskrypcji. Domyślnie Twoja subskrypcja odbiera zdarzenia cyklu życia. Więcej informacji: przeczytaj artykuł Zdarzenia cyklu życia subskrypcji Google Workspace.
Abonament Google Workspace

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

Zasób docelowy
Zasób Google Workspace, który chcesz monitorować. Ten zasób znajduje się w polu targetResource sekcji Abonament Google Workspace. Każda subskrypcja może mieć tylko monitorowania 1 zasobu. Aby dowiedzieć się, które zasoby Google Workspace Obsługiwany interfejs Google Workspace Events API – zobacz Obsługiwane zdarzenia Google Workspace
Typy zdarzeń
Typy zmian, o których chcesz otrzymywać powiadomienia zasobu docelowego. Na przykład, jeśli subskrybujesz pokoju Google Chat, możesz wybrać, czy chcesz otrzymywać wydarzenia na temat: pokoju i jego zasobów podrzędnych, takich jak członkostwo i wiadomości.
Punkt końcowy powiadomienia
Punkt końcowy, w którym Abonament Google Workspace otrzymuje zdarzenia. Interfejs Google Workspace Events API obsługuje tematy Google Cloud Pub/Sub jako i punktu końcowego powiadomień. Aby dowiedzieć się więcej o korzystaniu z Google Cloud Pub/Sub, zobacz Dokumentacja 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 poszczególnych przypadkach możliwy zasób docelowy.

Zasób docelowy Obsługiwane zdarzenia
Pokoje Google Chat
  • Wiadomości
  • Wspieranie kanału
  • Reakcje
  • Spacja
Użytkownicy Google Chat
  • Wspieranie kanału
Sale konferencyjne w Google Meet
  • Konferencje
  • Sesje uczestników
  • Nagrania
  • Transkrypcje
Użytkownicy Google Meet
  • Konferencje
  • Sesje uczestników
  • Nagrania
  • Transkrypcje

Więcej informacji znajdziesz w tych przewodnikach:

Struktura zdarzeń Google Workspace

Zdarzenia Google Workspace powiązane są ze zdarzeniem CloudEvents specyfikacja, To standardowy sposób opisywania danych zdarzeń. Google Workspace, zdarzenia zawierają następujące elementy:

  • Atrybuty CloudEvent.
  • Dane o zasobie Google Workspace, który zmienił się w wyniku wydarzenie

W poniższej sekcji opisano strukturę atrybutów i danych dla: Zdarzenia Google Workspace.

Atrybuty CloudEvent

Zdarzenia Google Workspace zawierają te wymagane elementy: 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: to jest 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, który reprezentuje zmianę w miejscu docelowym subskrypcji zasób, w tym zasoby podrzędne zasobu docelowego. W subskrypcji, możesz określić, czy ładunek ma zawierać dane o zmieniony zasób lub tylko nazwę zmienionego zasobu.

Jeśli na przykład masz subskrypcję pokoju czatu, może otrzymywać zdarzenia dotyczące nowych wiadomości w pokoju. Wydarzenia związane z: nowe wiadomości, dane zdarzenia będą zawierać ładunek danych z Google Chat Utworzone zasoby: spaces.message.

Podczas tworzenia subskrypcji możesz określić ilość danych zasobów zawarte w zdarzeniach odbieranych przez aplikację:

  • Uwzględnij dane zasobów: obejmuje niektóre lub wszystkie pola zmienionych wartości. . Jeśli zdecydujesz się uwzględnić dane zasobów, subskrypcja czas trwania jest ograniczony do 4 godzin lub 24 godzin, jeśli korzystasz z całej domeny .
  • Wyklucz dane zasobu: zawiera tylko nazwę zmienionej wartości. . Czas trwania subskrypcji wynosi maksymalnie 7 dni. Aby uzyskać szczegółowe informacje: w wydarzeniu, możesz utworzyć zapytanie dotyczące zasobu, używając jego nazwy.

Te opcje danych zdarzeń znajdują się tutaj: payloadOptions subskrypcji.

Zdarzenia jako komunikaty Google Cloud Pub/Sub

Subskrypcje Google Workspace Events API korzystają z Google Cloud Pub/Sub tematy jako punkt końcowy powiadomień, który otrzymuje Google Workspace. zdarzeń. 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 na nią odpowiedzieć do zdarzenia.

Poniższy przykład pokazuje wiadomość Google Cloud Pub/Sub, która zawiera wydarzenie 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, w tym: typ zdarzenia. W tym przypadku wydarzenie dotyczy zaktualizowanej wiadomości w kosmosu.
  • data: dane zdarzenia ze szczegółowymi informacjami o zaktualizowanych danych. Zasób spaces.message w formacie jako ciąg znaków zakodowany w standardzie Base64.
  • messageId: identyfikator wiadomości Google Cloud Pub/Sub.

Aby dowiedzieć się więcej o sposobie określania zdarzeń CloudEvents w Google Cloud Pub/Sub wiadomości znajdziesz w artykule Powiązanie protokołu Google Cloud Pub/Sub z CloudEvents.