Subskrybowanie wydarzeń w Google Chat

Ta strona opisuje zdarzenia w Google Chat, które aplikacja do obsługi czatu może subskrybować za pomocą interfejsu Google Workspace Events API. Gdy zdecydujesz, jakich typów zdarzeń potrzebujesz, utwórz subskrypcję, aby zacząć otrzymywać zdarzenia z Google Chat.

Oprócz subskrybowania zdarzeń możesz też wysyłać zapytania o zdarzenia, wywołując interfejs Google Chat API. Wywołanie interfejsu Chat API umożliwia okresowe pobieranie zdarzeń lub nadrabianie zaległości w przypadku zdarzeń, które mogły zostać pominięte w subskrypcji z powodu przerwy w działaniu usługi. Więcej informacji o sposobach odbierania zdarzeń z Google Chat i reagowania na nie znajdziesz w dokumentacji Google Chat w sekcji Praca ze zdarzeniami z Google Chat.

Obsługiwane zdarzenia w Google Chat

Subskrypcje Google Workspace umożliwiają otrzymywanie zdarzeń dotyczących tych typów zmian w Google Chat:

  • nowe, zaktualizowane lub usunięte wiadomości w pokoju;
  • nowe lub usunięte reakcje na wiadomość;
  • nowi, zaktualizowani lub usunięci użytkownicy w pokoju.
  • zmiany w pokoju subskrybowanym przez Ciebie, np. zaktualizowana nazwa lub opis pokoju.

Zasoby, które można monitorować pod kątem zdarzeń

Aby otrzymywać zdarzenia, musisz określić zasób Google Chat do monitorowania, który jest nazywany zasobem docelowym subskrypcji.

Interfejs Google Workspace Events API obsługuje te zasoby docelowe w Google Chat:

Zasób docelowy Format Ograniczenia
Spacja

//chat.googleapis.com/spaces/SPACE

gdzie SPACE to identyfikator w nazwie zasobu interfejsu Chat API space. Identyfikator możesz uzyskać z adresu URL pokoju lub za pomocą metody spaces.list().

 Użytkownik Google Chat lub aplikacja do obsługi czatu, która autoryzuje subskrypcję, musi być członkiem pokoju na swoim koncie Google Workspace lub Google Account. Obsługiwane:
Wszystkie pokoje użytkownika

//chat.googleapis.com/spaces/-

 Subskrypcja otrzymuje tylko zdarzenia dotyczące pokoi, w których użytkownik jest członkiem na swoim koncie Google Workspace lub Google. Obsługuje tylko uwierzytelnianie użytkownika.
Użytkownik

//cloudidentity.googleapis.com/users/USER

gdzie USER to identyfikator w nazwie zasobu interfejsu Chat API user. Więcej informacji znajdziesz w artykule Identyfikowanie i określanie użytkownikó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. Obsługuje tylko uwierzytelnianie użytkownika.

Typy zdarzeń do tworzenia subskrypcji

Podczas tworzenia subskrypcji użyj pola eventTypes[] , aby określić, jakie typy zdarzeń chcesz otrzymywać. Typy zdarzeń są formatowane zgodnie ze specyfikacją CloudEvents, np. google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Jeśli na przykład chcesz otrzymywać zdarzenia dotyczące dołączania użytkowników do pokoju w Google Chat, określ pokój jako zasób docelowy, a typ zdarzenia jako google.workspace.chat.membership.v1.created. Aby otrzymywać zdarzenia dotyczące dołączania danego użytkownika do dowolnego pokoju, określ użytkownika jako zasób docelowy, a typ zdarzenia jako google.workspace.chat.membership.v1.created. Więcej informacji o tym, jak działają zdarzenia, znajdziesz w artykule Struktura zdarzeń Google Workspace events.

W tabeli poniżej znajdziesz informacje o tym, które typy zdarzeń są obsługiwane w przypadku subskrypcji pokoi i subskrypcji użytkowników. Więcej informacji o wyjątkach dotyczących tego, co wywołuje zdarzenie, znajdziesz w sekcji Ograniczenia.

Typ zdarzenia Format Dane zasobu
Subskrypcje pokoi  
Opublikowano wiadomość.

google.workspace.chat.message.v1.created

space.message
Wiadomość została zaktualizowana.

google.workspace.chat.message.v1.updated

space.message
Wiadomość została usunięta.

google.workspace.chat.message.v1.deleted

space.message
Utworzono reakcję.

google.workspace.chat.reaction.v1.created

space.message.reaction
Reakcja została usunięta.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
Użytkownik został dodany do pokoju.

google.workspace.chat.membership.v1.created

space.membership
Użytkownik został zaktualizowany w pokoju.

google.workspace.chat.membership.v1.updated

space.membership
Użytkownik został usunięty z pokoju.

google.workspace.chat.membership.v1.deleted

space.membership
Pokój został zaktualizowany.

google.workspace.chat.space.v1.updated

space
Pokój został usunięty.

google.workspace.chat.space.v1.deleted

space
Subskrypcje użytkowników  
Użytkownik staje się członkiem pokoju.

Nie wszyscy nowi użytkownicy wywołują zdarzenia. Więcej informacji znajdziesz w sekcji Ograniczenia.

google.workspace.chat.membership.v1.created

space.membership
Zaktualizowano członkostwo użytkownika w pokoju.

google.workspace.chat.membership.v1.updated

space.membership
Użytkownik został usunięty jako bezpośredni członek pokoju.

google.workspace.chat.membership.v1.deleted

space.membership
Zaktualizowano stan przeczytania pokoju przez użytkownika. ( wersja przedpremierowa dla programistów)

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
Zaktualizowano stan przeczytania wątku przez użytkownika. ( wersja przedpremierowa dla programistów)

google.workspace.chat.threadReadState.v1.updated

threadReadState

Typy zdarzeń zbiorczych (tylko dane wyjściowe)

Oprócz otrzymywania typów zdarzeń, które subskrybujesz, aplikacja do obsługi czatu może też otrzymywać zdarzenia zbiorcze. Zdarzenie zbiorcze to zdarzenie, które reprezentuje wiele zdarzeń tego samego typu występujących w krótkim czasie. Ładunek zdarzenia zbiorczego zawiera listę wszystkich zmienionych zasobów.

Jeśli na przykład użytkownik doda jednocześnie 20 użytkowników do pokoju, aplikacja do obsługi czatu może otrzymać zdarzenie zbiorcze (google.workspace.chat.membership.v1.batchCreated). Ładunek zdarzenia zawiera listę wszystkich nowych zasobów Membership, które zostały utworzone, gdy użytkownik dodał członków do pokoju.

Zdarzenie zbiorcze otrzymujesz w przypadku każdego typu zdarzenia, który subskrybujesz, więc podczas tworzenia subskrypcji nie musisz określać zdarzeń zbiorczych. Jeśli na przykład subskrybujesz nowe reakcje (google.workspace.chat.reaction.v1.created), aplikacja do obsługi czatu jest automatycznie skonfigurowana do odbierania zbiorczych zdarzeń reakcji (google.workspace.chat.reaction.v1.batchCreated).

W tabeli poniżej znajdziesz możliwe zdarzenia zbiorcze w przypadku subskrypcji:

Typ zdarzenia zbiorczego Format
Opublikowano wiele wiadomości.

google.workspace.chat.message.v1.batchCreated
Zaktualizowano wiele wiadomości.

google.workspace.chat.message.v1.batchUpdated
Usunięto wiele wiadomości.

google.workspace.chat.message.v1.batchDeleted
Utworzono wiele reakcji.

google.workspace.chat.reaction.v1.batchCreated
Usunięto wiele reakcji.

google.workspace.chat.reaction.v1.batchDeleted
Do subskrybowanego pokoju dodano wielu użytkowników lub subskrybowany użytkownik został dodany do wielu pokoi.

google.workspace.chat.membership.v1.batchCreated
Zaktualizowano wiele członkostw w subskrybowanym pokoju lub w przypadku subskrybowanego użytkownika.

google.workspace.chat.membership.v1.batchUpdated
Z subskrybowanego pokoju usunięto wielu użytkowników lub subskrybowany użytkownik został usunięty z wielu pokoi.

google.workspace.chat.membership.v1.batchDeleted
Pokój ma wiele aktualizacji.

google.workspace.chat.space.v1.batchUpdated
Zaktualizowano wiele stanów przeczytania pokoju przez subskrybowanego użytkownika. ( wersja przedpremierowa dla programistów)

google.workspace.chat.spaceReadState.v1.batchUpdated
Zaktualizowano wiele stanów przeczytania wątku przez subskrybowanego użytkownika. ( wersja przedpremierowa dla programistów)

google.workspace.chat.threadReadState.v1.batchUpdated

Dane zdarzenia

W tej sekcji opisujemy dane zdarzenia i przykładowe ładunki zdarzeń w Google Chat.

Gdy abonament Google Workspace otrzyma zdarzenie z Google Chat, pole data zawiera ładunek zdarzenia. Ten ładunek zawiera informacje o zmienionym zasobie Google Workspace. Jeśli na przykład subskrybujesz zdarzenia dotyczące członkostwa w pokoju, ładunek tych zdarzeń zawiera informacje o spaces.membership zasobie, który uległ zmianie.

Dane zasobu w ładunku zdarzenia

Podczas tworzenia subskrypcji możesz określić, czy ładunek ma zawierać szczegóły zasobu, czy tylko jego nazwę. Jeśli na przykład chcesz otrzymywać zdarzenia dotyczące użytkowników w pokoju Google Chat, określ, które pola zasobu członkostwa chcesz otrzymywać w ładunku zdarzenia.

W tabeli poniżej znajdziesz przykłady ładunków JSON w przypadku subskrypcji pokoju Google Chat spaces/AAAABBBBBB. W przypadku każdego zdarzenia, które otrzymuje subskrypcja, ładunek pojawia się w polu data zdarzenia:

Przykład Typ zdarzenia Ładunek JSON

Użytkownik publikuje w pokoju wiadomość „Hello world”.

google.workspace.chat.message.v1.created

Zawiera dane zasobu:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

Nie zawiera danych zasobu:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
Użytkownik staje się menedżerem pokoju.

google.workspace.chat.membership.v1.updated

Zawiera dane zasobu:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}

Nie zawiera danych zasobu:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
Użytkownik zmienia opis pokoju na „Zespół sprzedaży Cymbal Labs”. google.workspace.chat.space.v1.updated

Zawiera dane zasobu:

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}

Nie zawiera danych zasobu:

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
Do pokoju dodano jednocześnie 2 użytkowników Google Chat. google.workspace.chat.membership.v1.batchCreated

Zawiera dane zasobu:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

Nie zawiera danych zasobu:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
Użytkownik reaguje na wiadomość emotikonem 😊. google.workspace.chat.reaction.v1.created

Zawiera dane zasobu:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

Nie zawiera danych zasobu:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
Użytkownicy reagują na wiadomość emotikonami 😊 i 😸. google.workspace.chat.reaction.v1.batchCreated

Zawiera dane zasobu:

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

Nie zawiera danych zasobu:

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
Użytkownik odwiedza nieprzeczytany pokój, co powoduje zaktualizowanie stanu przeczytania pokoju. ( wersja przedpremierowa dla programistów) google.workspace.chat.spaceReadState.v1.updated

Zawiera dane zasobu:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

Nie zawiera danych zasobu:

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
Użytkownik czyta wiadomość w wątku, co powoduje zaktualizowanie stanu przeczytania wątku. ( wersja przedpremierowa dla programistów) google.workspace.chat.threadReadState.v1.updated

Zawiera dane zasobu:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

Nie zawiera danych zasobu:

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}

Ograniczenia
  • W przypadku subskrypcji użytkowników zdarzenia dotyczące nowych użytkowników w wiadomościach bezpośrednich lub nienazwanych czatach grupowych (google.workspace.chat.membership.v1.created), są wywoływane dopiero po opublikowaniu pierwszej wiadomości.
  • Aby otrzymywać zdarzenia dotyczące członkostwa, użytkownik lub aplikacja do obsługi czatu musi być bezpośrednim członkiem pokoju. Jeśli użytkownik został dodany, zaktualizowany lub usunięty z pokoju pośrednio za pomocą grupy dyskusyjnej Google, subskrypcja nie będzie otrzymywać tych zdarzeń dotyczących członkostwa. Aby dowiedzieć się, jak działa członkostwo w grupach dyskusyjnych Google, przeczytaj artykuł Dodawanie grupy dyskusyjnej Google do pokoju.