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. Aby subskrybować zasób Google Workspace i otrzymywać odpowiednie zdarzenia, użyj interfejsu Google Workspace Events API.

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 Chat subskrybuje pokój Google Chat.
2. Pokój czatu 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. Zdarzenie zawiera dane o tym, co się zmieniło. Na przykład w przypadku zdarzenia dotyczącego nowej wiadomości zawiera ono szczegóły utworzonego zasobu Message.
4. Aplikacja Chat przetwarza wiadomość Google Cloud Pub/Sub, która zawiera zdarzenie, i w razie potrzeby podejmuje odpowiednie działania.

Ważne terminy

Do najczęściej używanych terminów w interfejsie Google Workspace Events API należą:

Zdarzenie Google Workspace

Zmiana w zasobie Google Workspace. Zdarzenia są formatowane zgodnie z specyfikacją CloudEvents i mogą być albo zdarzeniem subskrypcji albo zdarzeniem cyklu życia:

Zdarzenie subskrypcji

Zmiana w monitorowanym zasobie Google Workspace, np. nowa wiadomość w pokoju czatu. Możesz określić, ile szczegółów chcesz otrzymywać o zmienionym zasobie. Więcej informacji znajdziesz w artykule Struktura zdarzeń Google Workspace.

Zdarzenie cyklu życia

Zdarzenie dotyczące Twojego abonamentu Google Workspace. Zdarzenia cyklu życia informują o problemach i stanie subskrypcji, dzięki czemu możesz uniknąć pominięcia zdarzeń subskrypcji. Domyślnie subskrypcja zawsze otrzymuje zdarzenia cyklu życia. Więcej informacji znajdziesz w artykule Zdarzenia cyklu życia subskrypcji Google Workspace.

Abonament Google Workspace

Nazwana jednostka, która monitoruje zasób z aplikacji Google Workspace. Subskrypcja jest reprezentowana przez Subscription zasób. Subskrypcja jest definiowana 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ć zdarzenia dotyczące pokoju i jego zasobów podrzędnych, takich jak członkostwo i wiadomości.

Punkt końcowy powiadomień

Punkt końcowy, w którym abonament Google Workspace otrzymuje 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ć o zmienionych zasobach.

Obsługiwane zdarzenia Google Workspace

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

Więcej informacji znajdziesz w tych przewodnikach:

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

Struktura zdarzeń Google Workspace

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

• atrybuty CloudEvent;
• Dane o zasobie Google Workspace, który uległ zmianie w wyniku zdarzenia.

W sekcji poniżej znajdziesz informacje o strukturze atrybutów i danych zdarzeń 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 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 w Google Chat.

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

Te opcje danych zdarzenia są reprezentowane w payloadOptions polu subskrypcji.

Zdarzenia jako wiadomości 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 otrzymuje 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 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"
    }
}

Ten przykład zawiera 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 spaces.message zasobu sformatowane jako ciąg zakodowany w Base64.
• messageId: identyfikator wiadomości Google Cloud Pub/Sub.

Więcej informacji o tym, jak określa się CloudEvents w wiadomościach Google Cloud Pub/Sub , znajdziesz w artykule Google Cloud Pub/Sub Protocol Binding for CloudEvents.

Powiązane artykuły

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