Na tej stronie znajdziesz omówienie interfejsu Google Workspace Events API i dowiesz się, jak za jego pomocą subskrybować zdarzenia w Google Workspace.
Zdarzenia w Google Workspace przedstawiają zmiany w zasobach Google Workspace, takie jak ich utworzenie, aktualizacja lub usunięcie. Twoja aplikacja może zasubskrybować zasób Google Workspace, aby otrzymywać informacje o interesujących Cię wydarzeniach.
Jak aplikacja odbiera zdarzenia
Aby umożliwić aplikacji otrzymywanie zdarzeń Google Workspace, musisz utworzyć subskrypcje zasobów Google Workspace za pomocą interfejsu Google Workspace Events API.
W poniższym przykładzie interfejs Google Workspace Events API dostarcza zdarzenia do aplikacji Google Chat w ramach subskrypcji:
- Aplikacja do obsługi czatu subskrybuje pokój czatu.
- Pokój czatu się zmieni. Np. w pokoju opublikowano nową wiadomość.
- Google Chat przekazuje zdarzenie do tematu w
Google Cloud Pub/Sub, który służy jako punkt końcowy powiadomienia subskrypcji. Zdarzenie zawiera dane o tym, co się zmieniło. Na przykład zdarzenie dotyczące nowej wiadomości zawiera szczegóły utworzonego zasobu
Message
. - Aplikacja Google Chat przetwarza wiadomość z Google Cloud 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 interfejsie Google Workspace Events API:
- Wydarzenie Google Workspace
Zmiana zasobu Google Workspace. Zdarzenia są sformatowane za pomocą specyfikacji CloudEvents i mogą być zdarzeniami subskrypcji lub zdarzeniami cyklu życia:
- Zdarzenie subskrypcji
- Zmiana w zasobie Google Workspace, którą monitorujesz, np. nowa wiadomość w pokoju Google Chat. Możesz określić, ile szczegółów na temat zmienionego zasobu chcesz otrzymać. Szczegółowe informacje znajdziesz w artykule Struktura zdarzeń w Google Workspace.
- Zdarzenie cyklu życia
- Zdarzenie dotyczące Twojego abonamentu Google Workspace. Zdarzenia cyklu życia powiadamiają o problemach i stanie subskrypcji, dzięki czemu możesz uniknąć jej brakujących zdarzeń. Domyślnie subskrypcja zawsze odbiera zdarzenia cyklu życia. Szczegółowe informacje znajdziesz w artykule Zdarzenia cyklu życia subskrypcji Google Workspace.
- Abonament Google Workspace
Nazwana encja, która monitoruje zasób z aplikacji Google Workspace. Subskrypcja jest reprezentowana przez zasób
Subscription
. Subskrypcja jest określana na podstawie tych informacji:- Zasób docelowy
- Zasób Google Workspace, który chcesz monitorować.
Ten zasób jest widoczny w polu
targetResource
subskrypcji Google Workspace. Każda subskrypcja może monitorować tylko 1 zasób. Informacje o tym, które zasoby Google Workspace obsługuje interfejs Google Workspace Events API, znajdziesz w artykule Obsługiwane zdarzenia w Google Workspace. - Typy zdarzeń
- Typy zmian, o których chcesz otrzymywać powiadomienia dotyczące zasobu docelowego. Na przykład po zasubskrybowaniu pokoju Google Chat możesz wybrać, czy chcesz otrzymywać wydarzenia dotyczące tego pokoju i jego zasobów podrzędnych, takich jak subskrypcje i wiadomości.
- Punkt końcowy powiadomienia
- 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 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 przypadku każdego możliwego zasobu docelowego.
Zasób docelowy | Format | Obsługiwane zdarzenia | Ograniczenia (jeśli mają zastosowanie) | |
---|---|---|---|---|
Google Chat, | ||||
Pokoje Google Chat |
Aby zasubskrybować konkretny pokój:
Aby zasubskrybować wszystkie pokoje, do których należy ten użytkownik:
|
Więcej informacji znajdziesz w artykule Subskrybowanie wydarzeń w Google Chat. |
Użytkownik Google Chat, który autoryzuje subskrypcję, musi być użytkownikiem pokoju za pomocą swojego konta Google Workspace lub konta Google. | |
Użytkownicy Google Chat | //cloudidentity.googleapis.com/users/USER_ID |
Więcej informacji znajdziesz w artykule Subskrybowanie wydarzeń w Google Chat. |
Subskrypcja otrzymuje tylko zdarzenia dotyczące użytkownika, który autoryzował subskrypcję. Użytkownik nie może autoryzować subskrypcji w imieniu innych użytkowników. |
|
Google Meet | ||||
Sale konferencyjne w Google Meet | //meet.googleapis.com/spaces/SPACE_ID |
Szczegółowe informacje znajdziesz w artykule Subskrybowanie wydarzeń w Google Meet. |
||
Użytkownicy Google Meet | //cloudidentity.googleapis.com/users/USER_ID |
Szczegółowe informacje znajdziesz w artykule Subskrybowanie wydarzeń w Google Meet. |
Subskrypcja odbiera zdarzenia dotyczące sal konferencyjnych, w których użytkownik jest jednym z tych:
|
Struktura zdarzeń Google Workspace
Zdarzenia Google Workspace są zgodne ze specyfikacją CloudEvents, która jest standardowym sposobem opisywania danych zdarzeń. Zdarzenia Google Workspace obejmują:
W tej sekcji omawiamy strukturę atrybutów i danych zdarzeń Google Workspace.
Atrybuty CloudEvent
Zdarzenia Google Workspace zawierają te wymagane atrybuty CloudEvents:
Atrybut | Opis | Przykład |
---|---|---|
|
Typ danych przekazanych w zdarzeniu. |
|
|
Identyfikator zdarzenia 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żywana w przypadku tego zdarzenia. |
|
|
Zasób Google Workspace, w którym wystąpiło zdarzenie. |
|
|
Sygnatura czasowa momentu wystąpienia zdarzenia w formacie RFC 3339. |
|
|
Typ zdarzenia w Google Workspace. |
|
Dane zdarzenia
Dane zdarzenia to ładunek reprezentujący zmianę zasobu docelowego subskrypcji, w tym zasobów podrzędnych zasobu docelowego. W ramach subskrypcji możesz określić, czy ładunek ma zawierać dane o zmienionym zasobie czy tylko nazwę zmienionego zasobu.
Jeśli na przykład masz subskrypcję pokoju czatu, 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 Google Chat spaces.message
.
Podczas tworzenia subskrypcji możesz określić ilość danych dotyczących zasobów, które mają być uwzględniane w zdarzeniach odbieranych przez aplikację:
- Uwzględnij dane zasobu: obejmuje niektóre lub wszystkie pola zmienionego zasobu. Jeśli zdecydujesz się uwzględnić dane zasobów, czas trwania subskrypcji będzie ograniczony do 4 godzin lub 24 godzin, jeśli korzystasz z przekazywania dostępu w całej domenie.
- Wyklucz dane zasobu: zawiera tylko nazwę zmienionego zasobu. Czas trwania subskrypcji wynosi maksymalnie 7 dni. Aby uzyskać szczegółowe informacje o zdarzeniu, możesz utworzyć zapytanie dotyczące zasobu, korzystając z nazwy zasobu.
Te opcje danych zdarzeń znajdują się 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 wykonać działanie lub odpowiedzieć na zdarzenie.
Poniższy 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 ze szczegółowymi informacjami o zaktualizowanym zasobiespaces.message
w formacie ciągu zakodowanego w Base64.messageId
: identyfikator wiadomości Google Cloud Pub/Sub.
Więcej informacji o określaniu zdarzeń CloudEvents w wiadomościach Google Cloud Pub/Sub znajdziesz w artykule [GA4] Powiązanie protokołu Google Cloud Pub/Sub dla CloudEvents.
Powiązane artykuły
- Subskrybowanie wydarzeń w Google Chat
- Zdarzenia cyklu życia w przypadku subskrypcji Google Workspace
- Wybierz zakresy interfejsu Google Workspace Events API
- Tworzenie subskrypcji Google Workspace