이 페이지에서는 Google Chat 앱이 Google Workspace Events API를 사용하여 구독할 수 있는 Google Chat 이벤트를 설명합니다. 필요한 이벤트 유형을 결정한 후 구독을 만들어 Google Chat에서 이벤트 수신을 시작합니다.
이벤트 구독 외에도 Chat API를 호출하여 이벤트를 쿼리할 수도 있습니다. Chat API를 호출하면 주기적으로 이벤트를 검색하거나 서비스 중단으로 인해 구독에서 놓쳤을 수 있는 이벤트를 확인할 수 있습니다. Chat 이벤트를 수신하고 이에 응답하는 방법은 Chat 문서의 Google Chat에서 이벤트 작업하기를 참고하세요.
지원되는 Chat 대상 리소스
Google Workspace Events API는 다음과 같은 구독을 지원합니다.
- 스페이스(
space리소스로 표시됨) - 사용자(Cloud ID API
user리소스로 표시됨)
지원되는 Chat 이벤트
Google Workspace를 구독하면 Chat에서 다음과 같은 유형의 변경사항에 대한 이벤트를 수신할 수 있습니다.
- 스페이스의 신규, 업데이트 또는 삭제된 메시지입니다.
- 메시지에 대한 신규 또는 삭제된 리액션입니다.
- 스페이스의 신규, 업데이트 또는 삭제된 멤버입니다.
- 구독 중인 스페이스의 변경사항(예: 업데이트된 스페이스 이름 또는 설명)
구독 생성을 위한 이벤트 유형
정기 결제를 만들 때 eventTypes[] 필드를 사용하여 수신하려는 이벤트 유형을 지정합니다. 이벤트 유형은 CloudEvents 사양에 따라 형식이 지정됩니다(예: google.workspace.APPLICATION.RESOURCE.VERSION.ACTION).
예를 들어 Chat 스페이스에 참여하는 사용자에 대한 이벤트를 수신하려면 스페이스를 대상 리소스로 지정하고 이벤트 유형을 google.workspace.chat.membership.v1.created으로 지정합니다. 특정 사용자가 스페이스에 참여하는 것에 관한 이벤트를 수신하려면 사용자를 대상 리소스로 지정하고 이벤트 유형을 google.workspace.chat.membership.v1.created으로 지정합니다. 이벤트의 작동 방식에 대한 자세한 내용은 Google Workspace 이벤트의 구조를 참조하세요.
다음 표에는 스페이스 구독과 사용자 구독에 지원되는 이벤트 유형이 나와 있습니다. 이벤트를 트리거하는 요소에 관한 예외에 대해 알아보려면 제한사항을 참고하세요.
| 이벤트 유형 | 방식 | 리소스 데이터 | ||
|---|---|---|---|---|
| 스페이스 구독 | ||||
| 메시지가 게시됩니다. |
|
|
||
| 메시지가 업데이트됩니다. |
|
|
||
| 메시지가 삭제됩니다. |
|
|
||
| 반응이 생성됩니다. |
|
|
||
| 반응이 삭제되었습니다. |
|
|
||
| 멤버가 스페이스에 추가됩니다. |
|
|
||
| 스페이스에서 멤버가 업데이트됩니다. |
|
|
||
| 멤버가 스페이스에서 삭제됩니다. |
|
|
||
| 스페이스가 업데이트되었습니다. |
|
|
||
| 스페이스가 삭제되었습니다. |
|
|
||
| 사용자 구독 | ||||
| 사용자가 스페이스의 구성원이 됩니다.
모든 신규 회원이 이벤트를 트리거하는 것은 아닙니다. 자세한 내용은 제한사항을 참고하세요. |
|
|
||
| 사용자의 스페이스 멤버십이 업데이트됩니다. |
|
|
||
| 사용자가 스페이스의 직속 멤버에서 삭제됩니다. |
|
|
||
일괄 이벤트 유형 (출력 전용)
채팅 앱은 구독하는 이벤트 유형 수신 외에도 일괄 이벤트를 수신할 수 있습니다. 일괄 이벤트는 짧은 기간 내에 발생하는 동일한 유형의 여러 이벤트를 나타내는 이벤트입니다. 일괄 이벤트의 페이로드에는 변경된 모든 리소스의 목록이 포함됩니다.
예를 들어 사용자가 동시에 20명의 사용자를 스페이스에 추가하면 채팅 앱에서 일괄 이벤트(google.workspace.chat.membership.v1.batchCreated)를 수신할 수 있습니다. 이벤트 페이로드에는 사용자가 스페이스에 구성원을 추가할 때 생성된 모든 새 Membership 리소스 목록이 포함됩니다.
구독하는 이벤트 유형에 대해 일괄 이벤트를 수신하므로 구독을 만들 때 일괄 이벤트를 지정할 필요가 없습니다. 예를 들어 새 반응(google.workspace.chat.reaction.v1.created)을 구독하는 경우 채팅 앱이 일괄 반응 이벤트 (google.workspace.chat.reaction.v1.batchCreated)를 수신하도록 자동으로 구성됩니다.
다음 표는 구독에 가능한 일괄 이벤트를 보여줍니다.
| 일괄 이벤트 유형 | 방식 |
|---|---|
| 여러 메시지가 게시됩니다. |
|
| 여러 메시지가 업데이트됩니다. |
|
| 여러 개의 메시지가 삭제되었습니다. |
|
| 여러 리액션이 생성됩니다. |
|
| 여러 리액션이 삭제되었습니다. |
|
| 구독한 스페이스에 여러 멤버가 추가되었거나 구독한 사용자가 여러 스페이스에 추가되었습니다. |
|
| 구독한 스페이스에서 또는 구독한 사용자에게 여러 멤버십이 업데이트됩니다. |
|
| 구독 중인 스페이스에서 멤버 여러 명이 삭제되었거나 구독 중인 사용자가 여러 스페이스에서 삭제되었습니다. |
|
| 스페이스에 여러 업데이트가 있습니다. |
|
이벤트 데이터
이 섹션에서는 Chat의 이벤트에 대한 이벤트 데이터 및 페이로드의 예시를 설명합니다.
Google Workspace 구독이 Chat에서 이벤트를 수신하면 data 필드에 이벤트의 페이로드가 포함됩니다. 이 페이로드에는 변경된 Google Workspace 리소스에 대한 정보가 포함되어 있습니다. 예를 들어 스페이스에서 멤버십 이벤트를 구독한 경우 이러한 이벤트의 페이로드에는 변경된 spaces.membership 리소스에 대한 정보가 포함됩니다.
이벤트 페이로드의 리소스 데이터
구독을 만들 때 페이로드에 리소스에 대한 세부정보를 포함할지 아니면 리소스의 이름만 포함할지 지정할 수 있습니다. 예를 들어 Chat 스페이스의 구성원에 대한 이벤트를 수신하려면 이벤트 페이로드에서 수신할 멤버십 리소스의 필드를 지정하면 됩니다.
다음 표에는 Chat 스페이스 spaces/AAAABBBBBB 구독에 대한 JSON 페이로드의 예가 나와 있습니다. 정기 결제가 수신하는 각 이벤트에 대해 페이로드는 이벤트의 data 필드에 표시됩니다.
| 예 | 이벤트 유형 | JSON 페이로드 |
|---|---|---|
사용자가 스페이스에 'Hello world'라는 메시지를 게시합니다. |
|
리소스 데이터 포함
{
"message":
{
"name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD",
"sender":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "2023-09-07T21:37:36.260127Z",
"text": "Hello world",
"thread":
{
"name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE"
},
"space":
{
"name": "spaces/AAAABBBBBB"
},
"argumentText": "Hello world"
}
}
리소스 데이터 제외
{
"message":
{
"name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
}
}
|
| 사용자가 스페이스 관리자가 됩니다. |
|
리소스 데이터 포함
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321",
"state": "JOINED",
"member":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MANAGER"
}
}
리소스 데이터 제외
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
}
|
| 사용자가 스페이스에 대한 설명을 'Cymbal Labs 영업팀'으로 업데이트합니다. | google.workspace.chat.space.v1.updated |
리소스 데이터 포함
{
"space":
{
"name": "spaces/AAAABBBBBB",
"displayName": "Cymbal Sales",
"spaceThreadingState": "THREADED_MESSAGES",
"spaceType": "SPACE",
"spaceDetails":
{
"description": "Sales team for Cymbal Labs."
},
"spaceHistoryState": "HISTORY_ON"
}
}
리소스 데이터 제외
{
"space":
{
"name": "spaces/AAAABBBBBB"
}
}
|
| Chat 사용자 2명이 동시에 스페이스에 추가되었습니다. | google.workspace.chat.membership.v1.batchCreated |
리소스 데이터 포함
{
"memberships": [
{
"membership": {
"name": "spaces/AAAABBBBBB/members/1234567890987654321",
"state": "JOINED",
"member":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MEMBER"
}
},
{
"membership": {
"name": "spaces/AAAABBBBBB/members/987654321234567890",
"state": "JOINED",
"member":
{
"name": "users/987654321234567890",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MEMBER"
}
}
]
}
리소스 데이터 제외
{
"memberships": [
{
"membership": {
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
},
{
"membership": {
"name": "spaces/AAAABBBBBB/members/98765432123456789019"
}
}
]
}
|
| 사용자는 😊 이모티콘을 사용하여 메시지에 반응합니다. | google.workspace.chat.reaction.v1.created |
리소스 데이터 포함
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
"user":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😊"
}
}
}
리소스 데이터 생략
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
}
}
|
| 사용자는 😊 이모티콘과 받으세요 이모티콘으로 메시지에 반응합니다. | google.workspace.chat.reaction.v1.batchCreated |
리소스 데이터 포함
{
"reactions": [
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
"user":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😊"
}
}
},
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
"user":
{
"name": "users/98765431234564321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😸"
}
}
}
]
}
리소스 데이터 생략
{
"reactions": [
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
},
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
}
}
]
}
|
제한사항
-
사용자 구독의 경우 채팅 메시지 또는 이름이 지정되지 않은 그룹 채팅 (
google.workspace.chat.membership.v1.created)의 새 회원 관련 이벤트는 첫 번째 메시지가 게시된 후에만 트리거됩니다. - 스페이스 기록을 변경해도 업데이트된 스페이스 이벤트 (이벤트 유형:
google.workspace.chat.spaces.v1.updated)는 트리거되지 않습니다. - 멤버십 이벤트를 수신하려면 사용자가 스페이스의 직속 멤버여야 합니다. 사용자가 Google 그룹을 통해 스페이스에 간접적으로 추가, 업데이트 또는 삭제된 경우 구독은 이러한 멤버십 이벤트를 수신하지 않습니다. Google 그룹 멤버십 작동 방식을 알아보려면 스페이스에 Google 그룹 추가를 참고하세요.
관련 주제
- Google Workspace 이벤트의 구조
- OAuth 범위 선택
- Chat 이벤트를 수신하려면 구독 만들기