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

Ngoài việc đăng ký theo dõi 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ể bạn truy xuất các sự kiện theo định kỳ hoặc bắt kịp cho các sự kiện mà bạn có thể đã bỏ lỡ trong gói thuê bao do tình trạng ngừng dịch vụ. Để tìm hiểu về cách bạn có thể nhận và trả lời sự kiện Chat, hãy xem Thao tác với các sự kiện từ Google Chat trong Tài liệu về Chat.

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

Gói thuê bao của Google Workspace giúp bạn nhận các sự kiện về các loại thay đổi sau đây trong Chat:

  • Thư mới, đã cập nhật hoặc đã bị xóa 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á 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.

Những tài nguyên mà bạn có thể theo dõi để xác định sự kiện

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

API Sự kiện của Google Workspace hỗ trợ các tài nguyên mục tiêu sau đây đối với Chat:

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

//chat.googleapis.com/spaces/SPACE

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

Người dùng Chat cho phép gói thuê bao phải trở thành thành viên của không gian thông qua Google Workspace hoặc Google của họ Tài khoản.
Tất cả không gian dành cho người dùng

//chat.googleapis.com/spaces/-

Gói thuê bao này chỉ nhận sự kiện trong những không gian có người dùng thành viên thông qua Google Workspace hoặc Tài khoản Google của họ.
Người dùng

//cloudidentity.googleapis.com/users/USER

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

Gói thuê bao này chỉ nhận các sự kiện về người dùng đã uỷ quyền gói thuê bao. Người dùng không thể uỷ quyền gói thuê bao trên cho những người dùng khác.

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 eventTypes[] để chỉ định loại sự kiện bạn muốn nhận. Các loại sự kiện là 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 Chat khoảng trống, 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 tham gia bất kỳ không gian nào, bạn chỉ định người dùng là tài nguyên mục tiêu và loại sự kiện dưới dạng google.workspace.chat.membership.v1.created. Để tìm hiểu thêm về cách hoạt động của sự kiện, xem Cấu trúc của Google Workspace sự kiện.

Bảng sau đây cho biết những loại sự kiện được hỗ trợ cho gói thuê bao vào 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ề yếu tố kích hoạt sự kiện, xem 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 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 theo lô. Mộ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 thời gian ngắn khoảng thời gian cụ thể. Tải trọng của một sự kiện theo lô chứa danh sách tất cả của chúng tô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, Ứng dụng Chat 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 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 một gói thuê bao. Cho ví dụ: nếu bạn đăng ký nhận phản ứng mới (google.workspace.chat.reaction.v1.created), Ứng dụng Chat được định cấu hình tự động để nhận hàng loạt sự kiện phản ứng (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 sự kiện trong Trò chuyện.

Khi gói thuê bao Google Workspace của bạn nhận được một sự kiện từ Trò chuyện, data trường 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 thành viên trong một không gian, thì trọng tải của những sự kiện này sẽ chứa thông tin về 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 có muốn tải trọng bao gồm thông tin chi tiết về tài nguyên hoặc chỉ tên của tài nguyên. Cho ví dụ: nếu bạn muốn nhận sự kiện về thành viên trong một Chat , bạn có thể chỉ định các 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 cho một gói thuê bao 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 các mục đăng ký 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ỉ 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 một người dùng được thêm vào, được 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 này không nhận được các sự kiện dành cho hội viên đó. Để 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 Thêm một nhóm trên Google Groups vào một không gian.