Đăng ký nhận thông báo về sự kiện trong Google Chat

Trang này mô tả các sự kiện Google Chat mà ứ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ý sự kiện, bạn cũng có thể truy vấn sự kiện bằng cách gọi Chat API. Việc gọi Chat API cho phép bạn truy xuất các sự kiện theo định kỳ hoặc xem lại các sự kiện mà bạn có thể đã bỏ lỡ trong một gói thuê bao do sự cố ngừng hoạt động. Để tìm hiểu về các cách bạn có thể nhận và phản hồi các sự kiện trong Chat, hãy xem phần Xử lý các sự kiện từ Google Chat trong tài liệu về Chat.

Các sự kiện Chat được hỗ trợ

Gói thuê bao Google Workspace cho phép bạn nhận các sự kiện về các loại thay đổi sau trong Chat:

• Tin nhắn mới, đã cập nhật hoặc đã xoá trong không gian.
• Phản ứng mới hoặc đã xoá đối với một tin nhắn.
• Thành viên mới, đã cập nhật hoặc đã xoá trong không gian.
• Những thay đổi đối với không gian mà bạn đăng ký theo dõi, chẳng hạn như tên hoặc nội dung mô tả không gian đã được cập nhật.

Các tài nguyên mà bạn có thể theo dõi sự kiện

Để nhận sự kiện, bạn chỉ định một tài nguyên Chat để theo dõi, được gọi là tài nguyên mục tiêu của gói thuê bao.

Google Workspace Events API hỗ trợ các tài nguyên mục tiêu sau đây cho Chat:

Các loại sự kiện để tạo gói thuê bao

Khi tạo gói thuê bao, bạn sẽ 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 CloudEvents, chẳng hạn như google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Ví dụ: để nhận các sự kiện về người dùng tham gia một không gian Chat, bạn 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 các sự kiện về một người dùng cụ thể tham gia bất kỳ không gian nào, bạn chỉ định người dùng đó làm 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 sự kiện, hãy xem phần Cấu trúc của sự kiện trong Google Workspace.

Bảng sau đây cho biết những loại sự kiện được hỗ trợ cho gói thuê bao của không gian và gói thuê bao của người dùng. Để tìm hiểu về các trường hợp ngoại lệ về điều gì kích hoạt một sự kiện, hãy xem phần Giới hạn.

Loại sự kiện theo lô (chỉ có đầu ra)

Ngoài việc nhận 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 theo lô 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. Trọng tải của một sự kiện hàng loạt chứa danh sách tất cả tài nguyên đã thay đổi.

Ví dụ: nếu một người dùng thêm 20 người dùng vào một không gian cùng một lúc, thì ứng dụng Chat của bạn có thể nhận được một sự kiện hàng loạt (google.workspace.chat.membership.v1.batchCreated). Trọng tải sự kiện chứa danh sách tất cả tài nguyên Membership mới được tạo khi người dùng thêm các thành viên vào không gian.

Bạn sẽ nhận được 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 sự kiện theo lô khi tạo gói thuê bao. Ví dụ: nếu bạn đăng ký các lượt thể hiện 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 thể hiện cảm xúc 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:

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 cho sự kiện đó. Gói dữ liệu 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, thì 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 gói thuê bao, bạn có thể chỉ định xem bạn muốn tải trọng bao gồm 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 một không gian 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ề tải trọng JSON cho gói thuê bao của không gian Chat spaces/AAAABBBBBB. Đố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:

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

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

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

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

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

• Đối với các gói thuê bao người dùng, các 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ỉ kích hoạt sau khi đăng tin nhắn đầu tiên.
• Để nhận được sự kiện liên quan đến gói 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 xoá gián tiếp khỏi một không gian thông qua Nhóm Google, thì gói thuê bao sẽ không nhận được các sự kiện thành viên đó. Để tìm hiểu cách hoạt động của gói thành viên Google Groups, hãy xem bài viết Thêm nhóm trên Google Groups vào không gian.

Chủ đề có liên quan

• Cấu trúc của sự kiện trên Google Workspace
• Chọn phạm vi OAuth
• Tạo gói thuê bao để nhận sự kiện Chat