Đă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 trong Chat mà ứng dụng Chat có thể đăng ký bằng Google Workspace Events API. Sau khi quyết định loại sự kiện bạn cần, hãy tạo gói thuê bao để bắt đầu nhận sự kiện từ 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 Google Chat API. Việc gọi Chat API cho phép bạn truy xuất sự kiện theo định kỳ hoặc nắm bắt các sự kiện mà bạn có thể đã bỏ lỡ từ 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 sự kiện trong Chat, hãy xem bài viết Làm việc với các sự kiện từ Chat trong tài liệu về Chat.

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

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á tin nhắn 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á thành viên trong không gian.
  • Các thay đổi đối với không gian mà bạn đã đăng ký, chẳng hạn như tên hoặc nội dung mô tả không gian đã cập nhật.

Các tài nguyên mà bạn có thể giám sát để biết sự kiện

Để nhận sự kiện, bạn hãy chỉ định một tài nguyên trong Chat để giám sát. Tài nguyên này đượ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:

Tài nguyên mục tiêu Định dạng Giới hạn
Không gian

//chat.googleapis.com/spaces/SPACE

trong đó SPACE là mã nhận dạng trong tên tài nguyên của tài nguyên space trong Chat API. Bạn có thể lấy mã nhận dạng từ URL của không gian hoặc bằng phương thức spaces.list().

 Người dùng Chat hoặc ứng dụng Chat uỷ quyền cho gói thuê bao phải là thành viên của không gian thông qua Tài khoản Google hoặc Google Workspace của họ. Hỗ trợ:
Tất cả không gian của một người dùng

//chat.googleapis.com/spaces/-

 Gói thuê bao chỉ nhận các sự kiện cho những không gian mà người dùng là thành viên thông qua Tài khoản Google hoặc Google Workspace của họ. Chỉ hỗ trợ xác thực người dùng.
Người dùng

//cloudidentity.googleapis.com/users/USER

trong đó USER là mã nhận dạng trong tên tài nguyên của tài nguyên user trong Chat API. Để biết thông tin chi tiết, hãy xem bài viết Xác định và chỉ định người dùng Google Chat.

Gói thuê bao chỉ nhận các sự kiện về người dùng đã uỷ quyền cho gói thuê bao. Người dùng không thể uỷ quyền cho gói thuê bao thay mặt cho người dùng khác. Chỉ hỗ trợ xác thực người dùng.

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

Khi tạo gói thuê bao, hãy 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 không gian trong Chat, hãy chỉ định không gian là 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, hãy 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 sự kiện, hãy xem bài viết Cấu trúc của các 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 đối với không gian và gói thuê bao đối với người dùng. Để tìm hiểu về các trường hợp ngoại lệ về điều kiện kích hoạt sự kiện, hãy xem bài viết Giới hạn.

Loại sự kiện Định dạng Dữ liệu tài nguyên
Gói thuê bao đối với không gian  
Một tin nhắn được đăng.

google.workspace.chat.message.v1.created

space.message
Một tin nhắn được cập nhật.

google.workspace.chat.message.v1.updated

space.message
Một tin nhắn bị xoá.

google.workspace.chat.message.v1.deleted

space.message
Một phản ứng được tạo.

google.workspace.chat.reaction.v1.created

space.message.reaction
Một phản ứng bị xoá.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
Một thành viên được thêm vào không gian.

google.workspace.chat.membership.v1.created

space.membership
Một thành viên được cập nhật trong không gian.

google.workspace.chat.membership.v1.updated

space.membership
Một thành viên bị xoá khỏi không gian.

google.workspace.chat.membership.v1.deleted

space.membership
Không gian được cập nhật.

google.workspace.chat.space.v1.updated

space
Không gian bị xoá.

google.workspace.chat.space.v1.deleted

space
Gói thuê bao đối với người dùng  
Người dùng trở thành thành viên của một không gian.

Không phải tất cả thành viên mới đều kích hoạt sự kiện. Để biết thông tin chi tiết, hãy xem bài viết Giới hạn

google.workspace.chat.membership.v1.created

space.membership
Tư cách thành viên của người dùng đối với một không gian được cập nhật.

google.workspace.chat.membership.v1.updated

space.membership
Người dùng bị xoá khỏi vai trò thành viên trực tiếp của một không gian.

google.workspace.chat.membership.v1.deleted

space.membership

Các loại sự kiện hàng loạt (chỉ đầ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 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 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 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). Tải trọng của 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 bất kỳ loại sự kiện nào 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ý các phản ứng 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 phản ứng hàng loạt (google.workspace.chat.reaction.v1.batchCreated).

Bảng sau đây cho biết các sự kiện hàng loạt có thể có đối với một gói thuê bao:

Loại sự kiện hàng loạt Định dạng
Nhiều tin nhắn được đăng.

google.workspace.chat.message.v1.batchCreated
Nhiều tin nhắn được cập nhật.

google.workspace.chat.message.v1.batchUpdated
Nhiều tin nhắn bị xoá.

google.workspace.chat.message.v1.batchDeleted
Nhiều phản ứng được tạo.

google.workspace.chat.reaction.v1.batchCreated
Nhiều phản ứng bị xoá.

google.workspace.chat.reaction.v1.batchDeleted
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.

google.workspace.chat.membership.v1.batchCreated
Nhiều quyền thành viên được cập nhật trong không gian đã đăng ký hoặc cho người dùng đã đăng ký.

google.workspace.chat.membership.v1.batchUpdated
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.

google.workspace.chat.membership.v1.batchDeleted
Không gian có nhiều thông tin cập nhật.

google.workspace.chat.space.v1.batchUpdated

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 đó. 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 về quyền thành viên trong một không gian, thì tải trọng cho các sự kiện này chứa thông tin về spaces.membership tài nguyên đã thay đổi.

Dữ liệu tài nguyên trong tải trọng của 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 bạn muốn nhận các sự kiện về thành viên trong một không gian trong Chat, hãy chỉ định những trường nào của tài nguyên về quyền thành viên mà bạn muốn nhận trong tải trọng của sự kiện.

Bảng sau đây cung cấp các ví dụ về tải trọng JSON cho gói thuê bao đối với không gian trong 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:

Ví dụ Loại sự kiện Tải trọng JSON

Một người dùng đăng tin nhắn "Hello world" trong không gian.

google.workspace.chat.message.v1.created

Bao gồm dữ liệu tài nguyê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"
    }
}

Không bao gồm dữ liệu tài nguyên:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
Một người dùng trở thành người quản lý không gian.

google.workspace.chat.membership.v1.updated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
Một người dùng cập nhật nội dung mô tả của không gian thành "Nhóm bán hàng cho Cymbal Labs". google.workspace.chat.space.v1.updated

Bao gồm dữ liệu tài nguyên:

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "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/SPACE_ID"
    }
}
Hai người dùng Chat được thêm vào không gian cùng một lúc. google.workspace.chat.membership.v1.batchCreated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
Một người dùng phản ứng với tin nhắn bằng biểu tượng cảm xúc 😊. google.workspace.chat.reaction.v1.created

Bao gồm dữ liệu tài nguyên:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

Không bao gồm dữ liệu tài nguyên:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
Người dùng phản ứng với tin nhắn bằng biểu tượng cảm xúc 😊 và 😸. google.workspace.chat.reaction.v1.batchCreated

Bao gồm dữ liệu tài nguyên:

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

Không bao gồm dữ liệu tài nguyên:

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

Giới hạn
  • Đối với gói thuê bao đối vớ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 (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 sự kiện về quyền 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 vào một không gian thông qua một nhóm trên Google Groups, thì gói thuê bao sẽ không nhận được các sự kiện về quyền thành viên đó. Để hiểu cách hoạt động của quyền thành viên trong Nhóm Google, hãy xem bài viết Thêm Nhóm Google vào không gian.