Đă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 trên Google Chat mà một ứng dụng Google Chat có thể đăng ký nhận bằng Google Workspace Events API. Sau khi quyết định loại sự kiện bạn cần, hãy tạo một lượt đăng ký để bắt đầu nhận sự kiện từ Google Chat.

Ngoài việc đăng ký nhận sự kiện, bạn cũng có thể truy vấn sự kiện bằng cách gọi Chat API. Khi gọi Chat API, bạn có thể truy xuất các sự kiện theo đị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 hoạt động. Để tìm hiểu về những cách bạn có thể nhận và phản hồ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 trên Google Chat trong tài liệu về Chat.

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

Gói thuê bao Google Workspace cho phép bạn nhận các 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 đã 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, vừa cập nhật hoặc vừa bị 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ả mới của không gian.

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 cần 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 đích sau đây cho Chat:

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

Khi tạo một lượt đăng ký, bạn sẽ sử dụng trường eventTypes[] để chỉ định những loại sự kiện mà bạn muốn nhận. Các loại sự kiện được định dạng theo quy cách 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 trò chuyện, bạn chỉ định không gian đó làm tài nguyên đích 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 nhất định tham gia bất kỳ không gian nào, bạn chỉ định người dùng đó làm tài nguyên đích 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 phần Cấu trúc của các sự kiện trên Google Workspace.

Bảng sau đây cho biết những loại sự kiện được hỗ trợ cho việc đăng ký theo dõi không gian và đăng ký theo dõi người dùng. Để tìm hiểu về các trường hợp ngoại lệ đối với những yếu tố kích hoạt sự kiện, hãy xem phần Hạn chế.

Các 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ủa bạn cũng có thể nhận được các sự kiện hàng loạt. Sự kiện hàng loạt là 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 hàng loạt 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, 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). 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 các thành viên vào không gian.

Bạn sẽ nhận được một sự kiện hàng loạt 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 hàng loạt khi tạo một lượt đăng ký. Ví dụ: nếu bạn đăng ký nhận các lượt thể hiện cảm xúc mới (google.workspace.chat.reaction.v1.created), thì ứng dụng Chat của bạn sẽ tự động được định cấu hình để nhận các sự kiện thể hiện cảm xúc theo lô (google.workspace.chat.reaction.v1.batchCreated).

Bảng sau đây cho thấy các sự kiện hàng loạt 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à các 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 đó. 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ý nhận thông báo về 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 một 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 các sự kiện về thành viên trong một không gian trò chuyện, bạn có thể chỉ định những trường nào 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 một lượt đăng ký không gian trò chuyện 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/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",
        }
      }
    ]
}
      

• Đối với việc đăng ký theo dõi 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 tin nhắn đầu tiên được đăng.
• Để nhận được các sự kiện về tư cách thành viên, người dùng hoặc ứng dụng Chat phải là thành viên trực tiếp của không gian. Nếu họ được thêm, cập nhật hoặc xoá gián tiếp khỏi một không gian thông qua một nhóm trên Google Groups, thì dịch vụ đăng ký 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 tư cách thành viên trong nhóm trên Google Groups, hãy xem phần Thêm nhóm trên Google Groups vào 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 một gói thuê bao để nhận các sự kiện Chat