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

Na tej stronie znajdziesz omówienie interfejsu Google Workspace Events API oraz wyjaśnienie, jak można go używać do subskrybowania zdarzeń w Google Workspace.

Zdarzenia Google Workspace reprezentują zmiany w zasobach Google Workspace, takie jak tworzenie, aktualizowanie lub usuwanie zasobów. Aplikacja może subskrybować zasób Google Workspace, aby otrzymywać odpowiednie zdarzenia, które Cię interesują.

Jak aplikacja otrzymuje zdarzenia

Aby aplikacja mogła otrzymywać zdarzenia Google Workspace, użyj interfejsu Google Workspace Events API do utworzenia subskrypcji zasobów Google Workspace.

W tym przykładzie pokazujemy, jak interfejs Google Workspace Events API dostarcza zdarzenia do aplikacji Google Chat za pomocą subskrypcji:

1. Aplikacja do Google Chat subskrybuje pokój czatu.
2. Pokój na czacie ulega zmianie. Na przykład w pokoju opublikowano nową wiadomość.
3. Chat dostarcza zdarzenie do tematu w 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 w przypadku zdarzenia dotyczącego nowego komunikatu zawiera ono szczegóły utworzonego zasobu Message.
4. Aplikacja w Google Chat przetwarza wiadomość Google Cloud Pub/Sub zawierającą zdarzenie i w razie potrzeby podejmuje odpowiednie działania.

Ważna terminologia

Oto lista najczęściej używanych terminów w interfejsie Google Workspace Events API:

Wydarzenie w Google Workspace

Zmiana zasobu Google Workspace. Zdarzenia są formatowane zgodnie ze specyfikacją CloudEvents i mogą być zdarzeniem subskrypcji lub zdarzeniem cyklu życia:

Wydarzenie związane z subskrypcją

Zmiana w zasobie Google Workspace, który monitorujesz, np. nowa wiadomość w pokoju Google Chat. Możesz określić, jak szczegółowe informacje chcesz otrzymywać o zasobie, który uległ zmianie. Więcej informacji znajdziesz w artykule Struktura zdarzeń Google Workspace.

Zdarzenie cyklu życia

Wydarzenie dotyczące Twojej subskrypcji Google Workspace. Zdarzenia cyklu życia powiadamiają Cię o problemach i stanie subskrypcji, dzięki czemu możesz uniknąć pominięcia zdarzeń związanych z subskrypcją. Domyślnie subskrypcja zawsze otrzymuje zdarzenia związane z cyklem życia. Więcej informacji znajdziesz w artykule Zdarzenia związane z cyklem życia subskrypcji Google Workspace.

Abonament Google Workspace

Nazwany podmiot, który monitoruje zasób z aplikacji Google Workspace. Subskrypcja jest reprezentowana przez zasób Subscription. Subskrypcja jest określana przez te informacje:

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. Aby sprawdzić, które zasoby Google Workspace są obsługiwane przez interfejs Google Workspace Events API, zobacz Obsługiwane zdarzenia Google Workspace.

Typy zdarzeń

Typy zmian, o których chcesz otrzymywać powiadomienia w przypadku zasobu docelowego. Jeśli na przykład subskrybujesz pokój w Google Chat, możesz wybrać, czy chcesz otrzymywać powiadomienia o wydarzeniach dotyczących tego pokoju i jego zasobów podrzędnych, takich jak członkostwo i wiadomości.

Punkt końcowy powiadomień

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 zdarzenia, które chcesz otrzymywać w związku ze zmianami zasobów.

Obsługiwane wydarzenia Google Workspace

Zdarzenia, które może otrzymywać Twoja aplikacja, zależą od zasobu docelowego subskrypcji. W tabeli poniżej znajdziesz listę obsługiwanych zdarzeń w przypadku każdego możliwego zasobu docelowego.

Więcej informacji znajdziesz w tych przewodnikach:

• Subskrybowanie zdarzeń w Google Chat
• Subskrybowanie zdarzeń Dysku Google
• Subskrybowanie wydarzeń w Google Meet

Struktura wydarzeń Google Workspace

Zdarzenia Google Workspace są zgodne ze specyfikacją CloudEvents, która jest standardowym sposobem opisywania danych zdarzenia. Wydarzenia Google Workspace zawierają te informacje:

• Atrybuty zdarzenia w chmurze.
• Dane o zasobie Google Workspace, który uległ zmianie w wyniku zdarzenia.

W tej sekcji wyjaśniamy strukturę atrybutów i danych dotyczących wydarzeń w Google Workspace.

Atrybuty CloudEvent

Zdarzenia Google Workspace zawierają te wymagane atrybuty CloudEvents:

Dane zdarzenia

Dane zdarzenia to ładunek, który reprezentuje zmianę w zasobie docelowym subskrypcji, w tym w zasobach podrzędnych zasobu docelowego. W subskrypcji możesz określić, czy chcesz, aby ładunek zawierał dane o zmienionym zasobie, czy tylko jego nazwę.

Jeśli na przykład subskrybujesz pokój w Google Chat, 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 spaces.messageGoogle Chat.

Podczas tworzenia subskrypcji możesz określić, ile danych o zasobach ma być uwzględnianych w zdarzeniach otrzymywanych przez aplikację:

• Uwzględnij dane zasobu: zawiera niektóre lub wszystkie pola zmienionego zasobu. Jeśli zdecydujesz się uwzględnić dane zasobów, czas trwania subskrypcji jest ograniczony do 4 godzin lub 24 godzin, jeśli używasz delegowania w całej domenie.
• Wyklucz dane zasobu: zawiera tylko nazwę zmienionego zasobu. Subskrypcja trwa maksymalnie 7 dni. Aby uzyskać szczegółowe informacje o zdarzeniu, możesz wysłać zapytanie do zasobu, używając jego nazwy.

Te opcje danych o zdarzeniach są reprezentowane w polu payloadOptions subskrypcji.

Zdarzenia jako komunikaty Google Cloud Pub/Sub

Subskrypcje interfejsu Google Workspace Events API korzystają z 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 podjąć działanie lub odpowiedzieć na zdarzenie.

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

 {
    "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 pokoju.
• data: dane zdarzenia ze szczegółami zaktualizowanego zasobuspaces.message sformatowane jako ciąg znaków zakodowany w Base64.
• messageId: identyfikator wiadomości Google Cloud Pub/Sub.

Więcej informacji o tym, jak CloudEvents są określane w wiadomościach Google Cloud Pub/Sub, znajdziesz w artykule Google Cloud Pub/Sub Protocol Binding for CloudEvents (Powiązanie protokołu Google Cloud Pub/Sub z CloudEvents).

Powiązane artykuły

• Wybieranie zakresów interfejsu Google Workspace Events API
• Tworzenie subskrypcji Google Workspace