Trang này mô tả các sự kiện trên Google Chat mà một ứng dụng Google Chat có thể đăng ký bằng API Sự kiện của Google Workspace. Sau khi bạn quyết định loại sự kiện cần thiết, hãy tạo một gói thuê bao để bắt đầu nhận sự kiện từ Google Chat.
Ngoài việc đăng ký nhận thông tin về các sự kiện, bạn cũng có thể truy vấn các sự kiện bằng cách gọi Chat API. Khi gọi API Chat, bạn có thể truy xuất các sự kiện định kỳ hoặc nắm bắt các sự kiện mà bạn có thể đã bỏ lỡ trong một gói thuê bao do sự cố ngừng dịch vụ. Để tìm hiểu về những cách nhận và trả lời các sự kiện trên Chat, hãy xem phần Làm việc với các sự kiện từ Google Chat trong tài liệu về Chat.
Tài nguyên đích được hỗ trợ trên Chat
API Sự kiện của Google Workspace hỗ trợ các gói đăng ký cho:
- Không gian được biểu thị dưới dạng tài nguyên
space - Người dùng, được biểu thị dưới dạng tài nguyên
usercủa Cloud Identity API
Các sự kiện được hỗ trợ trong Chat
Các gói thuê bao của Google Workspace cho phép bạn nhận sự kiện về những loại thay đổi sau đây trong Chat:
- Tin nhắn mới, đã cập nhật hoặc đã bị xoá trong không gian.
- Phản ứng mới hoặc đã bị xoá đối với một tin nhắn.
- Thành viên mới, cập nhật hoặc bị xoá khỏi không gian.
- Thay đổi đối với không gian bạn đã đăng ký, chẳng hạn như mới cập nhật tên hoặc nội dung mô tả của không gian.
Các loại sự kiện để tạo gói thuê bao
Khi tạo một gói thuê bao, bạn sẽ dùng trường eventTypes[] để chỉ định loại sự kiện mà bạn muốn nhận. Các loại sự kiện được định dạng theo thông số kỹ thuật của CloudEvents, chẳng hạn như google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.
Ví dụ: để nhận sự kiện về việc người dùng tham gia phòng Chat, bạn sẽ chỉ định không gian làm tài nguyên mục tiêu và loại sự kiện là google.workspace.chat.membership.v1.created. Để nhận sự kiện về một người dùng cụ thể tham gia không gian bất kỳ, bạn cần chỉ định người dùng đó là tài nguyên mục tiêu và loại sự kiện là google.workspace.chat.membership.v1.created. Để tìm hiểu thêm về cách hoạt động của các sự kiện, hãy xem bài viết Cấu trúc của các sự kiện Google Workspace.
Bảng sau đây cho biết những loại sự kiện được hỗ trợ cho gói thuê bao không gian và gói thuê bao cho người dùng. Để tìm hiểu về các trường hợp ngoại lệ liên quan đến những yếu tố kích hoạt một sự kiện, hãy xem bài viết Các điểm hạn chế.
| Loại sự kiện | Định dạng | Dữ liệu tài nguyên | ||
|---|---|---|---|---|
| Việc đăng ký không gian | ||||
| Đã đăng một tin nhắn. |
|
|
||
| Đã cập nhật một tin nhắn. |
|
|
||
| Đã xoá một tin nhắn. |
|
|
||
| Một lượt thể hiện cảm xúc sẽ được tạo. |
|
|
||
| Một lượt thể hiện cảm xúc đã bị xoá. |
|
|
||
| Một thành viên đã được thêm vào không gian. |
|
|
||
| Một thành viên đã được cập nhật trong không gian. |
|
|
||
| Một thành viên đã bị xoá khỏi không gian. |
|
|
||
| Không gian đã được cập nhật. |
|
|
||
| Không gian đã bị xoá. |
|
|
||
| Gói thuê bao cho người dùng | ||||
| Người dùng sẽ trở thành thành viên của một không gian.
Không phải thành viên mới nào cũng kích hoạt sự kiện. Để biết chi tiết, vui lòng xem bài viết về Các điểm hạn chế |
|
|
||
| Tư cách thành viên của người dùng trong một không gian sẽ được cập nhật. |
|
|
||
| Người dùng đã bị xoá tư cách thành viên trực tiếp của không gian. |
|
|
||
Các loại sự kiện theo lô (chỉ kết quả đầu ra)
Ngoài việc nhận được các loại sự kiện mà bạn đăng ký, ứng dụng Chat cũng có thể nhận được các sự kiện hàng loạt. Sự kiện hàng loạt là một sự kiện đại diện cho nhiều sự kiện cùng loại xảy ra trong một khoảng thời gian ngắn. Tải trọng của một sự kiện theo lô chứa danh sách tất cả các tài nguyên đã thay đổi.
Ví dụ: nếu người dùng thêm 20 người dùng vào một không gian cùng lúc, ứng dụng Chat có thể nhận được một sự kiện theo lô (google.workspace.chat.membership.v1.batchCreated). Tải trọng sự kiện chứa danh sách tất cả các tài nguyên Membership mới được tạo khi người dùng thêm thành viên vào không gian.
Bạn sẽ nhận được một sự kiện theo lô cho mọi loại sự kiện mà bạn đăng ký. Vì vậy, bạn không cần chỉ định các sự kiện hàng loạt khi tạo gói thuê bao. Ví dụ: nếu bạn đăng ký nhận biểu tượng cảm xúc mới (google.workspace.chat.reaction.v1.created), ứng dụng Chat sẽ tự động được định cấu hình để nhận các sự kiện phản ứng hàng loạt (google.workspace.chat.reaction.v1.batchCreated).
Bảng sau đây cho thấy các sự kiện theo lô có thể xảy ra đối với một gói thuê bao:
| Loại sự kiện theo lô | Định dạng |
|---|---|
| Nhiều tin nhắn đã được đăng. |
|
| Nhiều tin nhắn đã được cập nhật. |
|
| Nhiều tin nhắn đã bị xoá. |
|
| Nhiều biểu tượng cảm xúc được tạo. |
|
| Nhiều lượt thể hiện cảm xúc đã bị xoá. |
|
| Nhiều thành viên được thêm vào không gian đã đăng ký hoặc người dùng đăng ký đã được thêm vào nhiều không gian. |
|
| Nhiều gói thành viên được cập nhật trong không gian đã đăng ký hoặc cho người dùng đã đăng ký. |
|
| Nhiều thành viên bị xoá khỏi không gian đã đăng ký hoặc người dùng đăng ký đã bị xoá khỏi nhiều không gian. |
|
| Không gian có nhiều nội dung cập nhật. |
|
Dữ liệu sự kiện
Phần này mô tả dữ liệu sự kiện và tải trọng mẫu cho các sự kiện trong Chat.
Khi gói thuê bao Google Workspace của bạn nhận được một sự kiện từ Chat, trường data sẽ chứa tải trọng của sự kiện đó. Tải trọng này có thông tin về tài nguyên Google Workspace đã thay đổi. Ví dụ: nếu bạn đã đăng ký các sự kiện thành viên trong một không gian, tải trọng cho các sự kiện này sẽ chứa thông tin về tài nguyên spaces.membership đã thay đổi.
Dữ liệu tài nguyên trong tải trọng sự kiện
Khi tạo một gói thuê bao, bạn có thể chỉ định xem bạn muốn tải trọng chứa thông tin chi tiết về tài nguyên hay chỉ tên của tài nguyên. Ví dụ: nếu muốn nhận sự kiện về thành viên trong phòng Chat, bạn có thể chỉ định những trường của tài nguyên thành viên mà bạn muốn nhận trong tải trọng sự kiện.
Bảng sau đây cung cấp ví dụ về các tải trọng JSON của gói thuê bao spaces/AAAABBBBBB trong phòng Chat. Đối với mỗi sự kiện mà gói thuê bao nhận được, tải trọng sẽ xuất hiện trong trường data của sự kiện:
| Ví dụ | Loại sự kiện | Tải trọng JSON |
|---|---|---|
Một người dùng đăng tin nhắn trong không gian với nội dung "Xin chào mọi người". |
|
Bao gồm cả dữ liệu tài nguyên
{
"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"
}
}
Không bao gồm dữ liệu tài nguyên
{
"message":
{
"name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
}
}
|
| Người dùng trở thành người quản lý không gian. |
|
Bao gồm cả dữ liệu tài nguyên
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321",
"state": "JOINED",
"member":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MANAGER"
}
}
Không bao gồm dữ liệu tài nguyên
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
}
|
| Một người dùng cập nhật nội dung mô tả về không gian thành "Nhóm bán hàng của Cymbal Labs". | google.workspace.chat.space.v1.updated |
Bao gồm cả dữ liệu tài nguyên
{
"space":
{
"name": "spaces/AAAABBBBBB",
"displayName": "Cymbal Sales",
"spaceThreadingState": "THREADED_MESSAGES",
"spaceType": "SPACE",
"spaceDetails":
{
"description": "Sales team for Cymbal Labs."
},
"spaceHistoryState": "HISTORY_ON"
}
}
Không bao gồm dữ liệu tài nguyên
{
"space":
{
"name": "spaces/AAAABBBBBB"
}
}
|
| Hai người dùng Chat được thêm vào không gian cùng lúc. | google.workspace.chat.membership.v1.batchCreated |
Bao gồm cả dữ liệu tài nguyên
{
"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"
}
}
]
}
Không bao gồm dữ liệu tài nguyên
{
"memberships": [
{
"membership": {
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
},
{
"membership": {
"name": "spaces/AAAABBBBBB/members/98765432123456789019"
}
}
]
}
|
| Người dùng thể hiện cảm xúc với tin nhắn bằng biểu tượng 😊. | google.workspace.chat.reaction.v1.created |
Bao gồm cả dữ liệu tài nguyên
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
"user":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😊"
}
}
}
Bỏ qua dữ liệu tài nguyên
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
}
}
|
| Người dùng thể hiện cảm xúc với tin nhắn bằng biểu tượng cảm xúc 😊 và biểu tượng cảm xúc 😸. | google.workspace.chat.reaction.v1.batchCreated |
Bao gồm cả dữ liệu tài nguyên
{
"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": "😸"
}
}
}
]
}
Bỏ qua dữ liệu tài nguyên
{
"reactions": [
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
},
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
}
}
]
}
|
Các điểm hạn chế
-
Đối với các gói thuê bao của người dùng, sự kiện về thành viên mới trong tin nhắn trực tiếp hoặc cuộc trò chuyện nhóm chưa đặt tên (
google.workspace.chat.membership.v1.created), chỉ được kích hoạt sau khi người dùng đăng tin nhắn đầu tiên. - Các thay đổi đối với nhật ký của không gian sẽ không kích hoạt các sự kiện đã cập nhật của không gian (Loại sự kiện:
google.workspace.chat.spaces.v1.updated). - Để nhận được các sự kiện dành cho thành viên, người dùng phải là thành viên trực tiếp của không gian. Nếu một người dùng được thêm, cập nhật hoặc bị xoá gián tiếp vào không gian thông qua một Nhóm trên Google, thì gói thuê bao sẽ không nhận được những sự kiện thành viên đó. Để tìm hiểu cách hoạt động của thành viên trong nhóm trên Google Groups, hãy xem phần Thêm một nhóm trên Google Groups vào một không gian.
Chủ đề có liên quan
- Cấu trúc của các sự kiện trên Google Workspace
- Chọn phạm vi OAuth
- Tạo gói thuê bao để nhận các sự kiện trong Chat