Subskrybowanie wydarzeń w Google Chat

Na tej stronie opisaliśmy zdarzenia w Google Chat, które aplikacja do Google Chat 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 zdarzeniach, które mogły zostać pominięte w subskrypcji z powodu przerwy w działaniu. Aby dowiedzieć się, jak odbierać zdarzenia z Google Chat i na nie odpowiadać, zapoznaj się z artykułem Praca ze zdarzeniami z Google Chat w dokumentacji 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ść;
• nowych, zaktualizowanych lub usuniętych członków pokoju;
• Zmiany w pokoju, który subskrybujesz, takie jak zaktualizowana nazwa lub opis pokoju.
• zmiany dostępności użytkownika,
• Zmiany w spaceReadState lub threadReadState użytkownika.

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

Aby otrzymywać zdarzenia, musisz określić zasób Google Chat, który chcesz monitorować. Jest on nazywany zasobem docelowym subskrypcji.

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

Typy zdarzeń do tworzenia subskrypcji

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

Jeśli na przykład chcesz otrzymywać zdarzenia dotyczące użytkowników dołączających do pokoju czatu, 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.

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

Typy zdarzeń zbiorczych (tylko dane wyjściowe)

Oprócz typów zdarzeń, które subskrybujesz, aplikacja Google Chat 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 do pokoju 20 użytkowników jednocześnie, aplikacja Google Chat 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ł osoby do pokoju.

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

W tabeli poniżej znajdziesz możliwe zdarzenia zbiorcze dotyczące subskrypcji:

Dane zdarzeń

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

Gdy Twoja subskrypcja Google Workspace otrzyma zdarzenie z Google Chat, pole data będzie zawierać ładunek zdarzenia. Ten ładunek zawiera informacje o zasobie Google Workspace, który uległ zmianie. Jeśli na przykład subskrybujesz zdarzenia związane z członkostwem w pokoju, ładunek tych zdarzeń zawiera informacje o zasobie spaces.membership, który uległ zmianie.

Dane zasobu w ładunku zdarzenia

Podczas tworzenia subskrypcji możesz określić, czy ładunek ma zawierać szczegółowe informacje o zasobie, 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 użytkownika mają być uwzględniane w ładunku zdarzenia.

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

{
    "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"
    }
}
      

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
      

{
    "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"
    }
}
      

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
      

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

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
      

{
    "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"
          }
        }
    ]
}
      

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
      

{
    "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"
    }
}
      

{
    "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": "😸"
            }
          }
        }
    ]
}
      

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
      

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

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
      

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

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

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE",
        "customStatus": {
          "text": "Be right back",
          "emoji": {
            "unicode": "👟"
          },
          "expireTime": "2026-03-24T18:38:05.583655Z"
        }
    }
}
      

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
      

Ograniczenia ogólne

• Aby otrzymywać zdarzenia dotyczące subskrypcji, użytkownik lub aplikacja Google Chat musi być bezpośrednim użytkownikiem pokoju. Jeśli zostali dodani, zaktualizowani lub usunięci pośrednio z pokoju za pomocą grupy dyskusyjnej Google, subskrypcja nie otrzymuje 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.

Subskrypcje użytkownika

• W przypadku subskrypcji użytkowników zdarzenia dotyczące nowych członków społeczności w czatach lub czatach grupowych bez nazwy (google.workspace.chat.membership.v1.created) są wywoływane dopiero po opublikowaniu pierwszej wiadomości.

Subskrypcje klientów

W przypadku subskrypcji klientów obowiązują te ograniczenia:

• Organizacja Google Workspace musi mieć co najmniej 1 licencję SKU Enterprise.
• Aplikacja Google Chat może utworzyć tylko jedną subskrypcję klienta dla danej organizacji Google Workspace. Organizacja Google Workspace może mieć łącznie do 5 subskrypcji klientów (utworzonych przez różne aplikacje do Google Chat).

W przypadku subskrypcji klientów dostarczanie zdarzeń podlega tym ogólnym regułom:

• Zdarzenia w pokoju: dostarczane tylko wtedy, gdy zdarzenie występuje w pokoju zarządzanym przez organizację Google Workspace.
• Zdarzenia użytkownika: są dostarczane tylko wtedy, gdy zdarzenie występuje u użytkownika należącego do Twojej organizacji Google Workspace.

Jedynym wyjątkiem od tych zasad są wydarzenia związane z subskrypcją. Twoja subskrypcja może otrzymywać zdarzenia dotyczące użytkowników zarówno z pokoi zarządzanych przez Twoją organizację, jak i z pokoi zarządzanych przez organizacje zewnętrzne, ale sposób ich dostarczania zależy od tego, która organizacja zarządza pokojem:

pokoje zarządzane przez Twoją organizację Google Workspace,

Jeśli w pokoju zarządzanym przez organizację Google Workspace nastąpi zmiana członkostwa, zostanie ona dostarczona jako zdarzenie w pokoju.

Nazwa zasobu zdarzenia dotyczącego pokoju ma ten format:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Pokoje zarządzane przez organizacje zewnętrzne

Jeśli członkostwo użytkownika zarządzanego przez Twoją organizację Google Workspace zmieni się w pokoju zarządzanym przez organizację zewnętrzną (np. w pokoju zewnętrznym lub na czacie utworzonym przez użytkownika zewnętrznego), Twoja subskrypcja otrzyma to zdarzenie jako zdarzenie użytkownika.

Nazwa zasobu zdarzenia użytkownika ma taki format:

users/{userId}/userEvents/{userEventId}

Powiązane artykuły

• Struktura zdarzeń Google Workspace
• Wybieranie zakresów protokołu OAuth
• Utworzenie subskrypcji, aby otrzymywać zdarzenia z Google Chat.