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

Zdarzenia Google Workspace reprezentują zmiany w zasobach Google Workspace, np. utworzenie, zaktualizowanie lub usunięcie zasobu. Użyj interfejsu Google Workspace Events API, aby zasubskrybować zasób Google Workspace i otrzymywać odpowiednie zdarzenia.

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.

Poniższy przykład pokazuje, jak interfejs Google Workspace Events API dostarcza zdarzenia do aplikacji Chat za pomocą subskrypcji:

1. Aplikacja do Google Chat subskrybuje pokój czatu w Google Chat.
2. Pokój czatu ulegnie 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 działania.

Ważna terminologia

Typowe terminy używane w interfejsie Google Workspace Events API to:

Wydarzenie Google Workspace

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

Wydarzenie związane z subskrypcją

Zmiana w zasobie Google Workspace, który monitorujesz, np. nowa wiadomość w pokoju czatu. 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 Twojego abonamentu Google Workspace. Zdarzenia związane z cyklem życia subskrypcji powiadamiają Cię o problemach i stanie subskrypcji, dzięki czemu nie przegapisz żadnych zdarzeń związanych z subskrypcją. Domyślnie subskrypcja zawsze otrzymuje zdarzenia cyklu ż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 abonamentu 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 czatu, możesz wybrać, czy chcesz otrzymywać powiadomienia o przestrzeni i jej zasobach podrzędnych, takich jak członkostwo i wiadomości.

Punkt końcowy powiadomień

Punkt końcowy, w którym abonament 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 zdarzenia Google Workspace

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

Więcej informacji znajdziesz w tych przewodnikach:

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

Struktura zdarzeń 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 ładunek ma zawierać dane o zmienionym zasobie, czy tylko jego nazwę.

Jeśli na przykład subskrybujesz pokój czatu, możesz otrzymywać informacje o nowych wiadomościach w tym pokoju czatu. 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 o zasobach ma być uwzględnianych w zdarzeniach otrzymywanych przez aplikację.

Te opcje danych o zdarzeniach są reprezentowane 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 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"
    }
}

Ten przykład zawiera 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 w formacie ciągu zakodowanego 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 abonamentu Google Workspace