Na tej stronie znajdziesz omówienie interfejsu Google Workspace Events API oraz wyjaśnienie, jak możesz go używać do subskrybowania zdarzeń w Google Workspace.
Zdarzenia Google Workspace odzwierciedlają zmiany w zasobach Google Workspace, na przykład tworzenie, aktualizowanie i usuwanie zasobów. Aplikacja może subskrybować zasób Google Workspace, aby otrzymywać odpowiednie zdarzenia, które Cię interesują.
Jak aplikacja otrzymuje zdarzenia
Aby umożliwić aplikacji otrzymywanie zdarzeń Google Workspace, użyj interfejsu Google Workspace Events API do tworzenia subskrypcji zasobów Google Workspace.
W tym przykładzie interfejs Events API w Google Workspace przesyła zdarzenia do aplikacji Google Chat za pomocą subskrypcji:
- Aplikacja Google Chat subskrybuje pokój czatu.
- Pokój czatu zmienia się. Na przykład nowa wiadomość jest publikowana w pokoju.
- Chat przekazuje 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 zdarzenie dotyczące nowego komunikatu zawiera informacje o utworzonym zasobie
Message. - Aplikacja Google Chat przetwarza wiadomość Google Cloud Pub/Sub zawierającą zdarzenie i w razie potrzeby podejmuje działanie.
Ważna terminologia
Oto lista często używanych terminów w interfejsie Events API w Google Workspace:
- Zdarzenie Google Workspace
zmiana zasobu Google Workspace. Zdarzenia są formatowane zgodnie ze specyfikacją CloudEvents i mogą być zdarzeniami subskrypcji lub zdarzeniami cyklu życia:
- Zdarzenie dotyczące subskrypcji
- Zmiana w zasobach Google Workspace, które monitorujesz, np. nowa wiadomość w pokoju Google Chat. Możesz określić, ile szczegółów dotyczących zmienionego zasobu chcesz otrzymywać. Więcej informacji znajdziesz w artykule Struktura zdarzeń Google Workspace.
- Zdarzenie cyklu życia
- Zdarzenie dotyczące subskrypcji Google Workspace. Zdarzenia cyklu życia informują o problemach i stanie subskrypcji, dzięki czemu możesz uniknąć pomijania zdarzeń związanych z subskrypcją. Domyślnie subskrypcja zawsze otrzymuje zdarzenia cyklu życia. Szczegółowe informacje znajdziesz w artykule Zdarzenia cyklu życia subskrypcji Google Workspace.
- Abonament Google Workspace
Nazwana nazwa, która monitoruje zasób z aplikacji Google Workspace. Subskrypcję reprezentuje 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
targetResourcew 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 Events API w Google Workspace, przeczytaj artykuł 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ć zdarzenia dotyczące tego pokoju i jego zasobów podrzędnych, takich jak członkostwa 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 używaniu Google Cloud Pub/Sub znajdziesz w dokumentacji Google Cloud Pub/Sub.
- Opcje ładunku
- Dane zdarzenia dotyczące zmienionych zasobów, które chcesz otrzymywać.
Obsługiwane zdarzenia Google Workspace
Zdarzenia, które może otrzymywać Twoja aplikacja, zależą od docelowego zasobu w Twojej subskrypcji. Tabela poniżej zawiera listę obsługiwanych zdarzeń dla każdego możliwego typu zasobu docelowego.
| Zasób docelowy | Obsługiwane zdarzenia |
|---|---|
| Pokoje Google Chat |
|
| Użytkownicy Google Chat |
|
| Sale konferencyjne w Google Meet |
|
| Użytkownicy Google Meet |
|
Więcej informacji znajdziesz w tych przewodnikach:
Struktura zdarzeń Google Workspace
Zdarzenia Google Workspace są zgodne ze specyfikacją CloudEvents, która jest standardowym sposobem opisywania danych zdarzeń. Zdarzenia Google Workspace zawierają:
W tej sekcji opisano strukturę atrybutów i danych dotyczących zdarzeń Google Workspace.
Atrybuty CloudEvent
Zdarzenia Google Workspace zawierają te wymagane atrybuty CloudEvents:
| Atrybut | Opis | Przykład |
|---|---|---|
|
Typ danych przekazanych w zdarzeniu. |
|
|
Identyfikator CloudEvent. |
|
|
Źródło zdarzenia. W przypadku zdarzeń Google Workspace jest to pełna nazwa zasobu subskrypcji. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
Wersja specyfikacji CloudEvents użyta w przypadku tego zdarzenia. |
|
|
Zasób Google Workspace, w którym wystąpiło zdarzenie. |
|
|
Sygnatura czasowa zdarzenia w formacie RFC 3339. |
|
|
Typ zdarzenia Google Workspace. |
|
Dane zdarzenia
Dane zdarzenia to ładunek, który reprezentuje zmianę zasobu docelowego subskrypcji, w tym jego zasobów podrzędnych. W subskrypcji możesz określić, czy dane w pliku payload mają zawierać informacje o zmienionym zasobie, czy tylko jego nazwę.
Jeśli na przykład masz subskrypcję pokoju czatu, możesz otrzymywać wydarzenia dotyczące nowych wiadomości w pokoju. W przypadku zdarzeń dotyczących nowych wiadomości dane zdarzenia zawierają ładunek z utworzonym zasobem Google Chatspaces.message.
Podczas tworzenia subskrypcji możesz określić, ile danych o zasobach ma być uwzględnionych w zdarzeniach otrzymywanych przez Twoją 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 delegacji na poziomie domeny.
- Wyklucz dane zasobu: zawiera tylko nazwę zmienionego zasobu. Czas trwania subskrypcji wynosi do 7 dni. Aby uzyskać szczegółowe informacje o zdarzeniu, możesz wysłać zapytanie do zasobu, podając jego nazwę.
Te opcje danych zdarzeń są widoczne w polu payloadOptions w 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 zareagować na zdarzenie.
Ten 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 wydarzenie dotyczy zaktualizowanej wiadomości w pokoju.data: dane zdarzenia zawierające szczegółowe informacje o zaktualizowanymspaces.messageźródle zapisane 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 (Google Cloud Pub/Sub Protocol Binding for CloudEvents).