Đă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 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 gói thuê bao để bắt đầu nhận các sự kiện từ Google Chat.

Ngoài việc đăng ký sự kiện, bạn cũng có thể truy vấn các sự kiện bằng cách gọi API Chat. 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ỡ từ một gói thuê bao do tình trạng ngừng dịch vụ. Để tìm hiểu về những cách bạn có thể nhận và trả lời các sự kiện trong 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 của Chat.

Các tài nguyên đích được hỗ trợ của Chat

API Sự kiện của Google Workspace hỗ trợ các gói thuê bao:

  • 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 user của API Cloud Identity

Sự kiện trong Chat được hỗ trợ

Các gói thuê bao của 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 đã bị xoá trong không gian.
  • Phản ứng mới hoặc đã bị xoá đối với một tin nhắ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ư cập nhật tên không gian hoặc nội dung mô tả.

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

Khi tạo một gói thuê bao, bạn cầ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 quy cách của CloudEvents, chẳng hạn như google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

Ví dụ: để nhận các sự kiện về việc người dùng tham gia phòng Chat, bạn sẽ 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, 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 sự kiện, hãy xem bài viết Cấu trúc của sự kiện Google Workspace.

Bảng sau đây cho biết những loại sự kiện được hỗ trợ đối với gói thuê bao không gian và gói thuê bao đối với người dùng. Để tìm hiểu về các ngoại lệ về 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
Gói đăng ký tham gia không gian  
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
Đã tạo một lượt thể hiện cảm xúc.

google.workspace.chat.reaction.v1.created

space.message.reaction
Một lượt thể hiện cảm xúc đã 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
Đã cập nhật một thành viên trong không gian.

google.workspace.chat.membership.v1.updated

space.membership
Một thành viên sẽ 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 cho người dùng  
Người dùng sẽ trở thành thành viên của 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 thông tin chi tiết, vui lòng xem bài viết về Các điểm hạn chế

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 sẽ được cập nhật.

google.workspace.chat.membership.v1.updated

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

google.workspace.chat.membership.v1.deleted

space.membership

Các loại sự kiện theo lô (chỉ đối với đầ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 sự kiện theo lô. 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. Tải trọng của một sự kiện theo lô chứa danh sách tất 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ủ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ả 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 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 phản ứng 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 trình bày các sự kiện có thể xảy ra theo lô cho một gói thuê bao:

Loại sự kiện theo lô Đị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 thư sẽ bị xoá.

google.workspace.chat.message.v1.batchDeleted
Bạn có thể tạo nhiều biểu tượng cảm xúc.

google.workspace.chat.reaction.v1.batchCreated
Nhiều biểu tượng cảm xúc đã 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 gói thành viên sẽ đượ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 này có nhiều nội dung 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à 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 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, thì tải trọng của 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 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 gói 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 cho gói thuê bao của phòng 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 một tin nhắn trong không gian có nội dung "Xin chào mọi người".

google.workspace.chat.message.v1.created

Bao gồm 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 sẽ 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/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"
    }
}
Người dùng cập nhật nội dung mô tả không gian thành "Nhóm bán hàng của Cymbal Labs". google.workspace.chat.space.v1.updated
Bao gồm 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 một lúc. google.workspace.chat.membership.v1.batchCreated
Bao gồm 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"
          }
        }
    ]
}
Một 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 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 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 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 tin nhắn đầu tiên được đăng.
  • Để nhận 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 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 một nhóm trên Google Groups, 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 tư cách thành viên trong nhóm trên Google Groups, hãy xem bài viết Thêm một nhóm trên Google Groups vào không gian.