Xác định và chỉ định người dùng Google Chat

Trang này giải thích cách các ứng dụng Google Chat và nhà phát triển có thể xác định và chỉ định người dùng Chat.

Để thực hiện bất kỳ thao tác nào sau đây, ứng dụng Chat hoặc nhà phát triển phải chỉ định một người dùng:

Cách Chat xác định người dùng

API Google Chat tạo một tài nguyên User cho mỗi người và ứng dụng sử dụng Chat. Tài nguyên User chứa các trường sau:

  • name: Tên tài nguyên, được định dạng là users/{user}, trong đó {user} đại diện cho một giá trị nhận dạng riêng biệt và ổn định. Bạn có thể dùng users/app làm biệt hiệu cho ứng dụng Chat gọi điện.
  • displayName: Chỉ đầu ra. Tên hiển thị của người dùng.
  • avatarUrl: Chỉ đầu ra. URL hình ảnh đại diện của người dùng.
  • email: Chỉ đầu ra. Địa chỉ email của người dùng.
  • domainId: Giá trị nhận dạng duy nhất của miền Google Workspace của người dùng.
  • type: Loại người dùng. Tham số này cho biết người dùng là ứng dụng trò chuyện (BOT) hay một người (HUMAN).
  • isAnonymous: Chỉ đầu ra. Khi true, cho biết người dùng đã bị xoá hoặc hồ sơ của họ không xuất hiện.

Chi tiết hồ sơ người dùng và quy tắc hiển thị

Khi gọi API Tin nhắn và API Thành viên bằng cách sử dụng xác thực người dùng, Google Chat API sẽ điền thông tin chi tiết về hồ sơ vào tài nguyên User. API này điền sẵn displayName, email và avatarUrl cho cả người dùng nội bộ (trong tổ chức Google Workspace của bạn) và người dùng bên ngoài (trong các tổ chức bên ngoài hoặc Tài khoản Google cá nhân).

Sau đây là ví dụ về những vị trí mà API điền sẵn hồ sơ người dùng:

  • sender của Message.
  • Người dùng trong thư annotations, chẳng hạn như người dùng @mentions.
  • member trong tài nguyên Membership.

Quy tắc về quyền riêng tư và khả năng hiển thị

Để bảo vệ quyền riêng tư của người dùng, Google Chat API áp dụng các quy tắc hiển thị cụ thể khi xác định có nên điền sẵn thông tin chi tiết về hồ sơ của người dùng hay không:

  • Hồ sơ có thông tin: API sẽ điền sẵn thông tin chi tiết về hồ sơ (displayName, email và avatarUrl xuất hiện, còn isAnonymous là false) nếu người dùng đã chấp nhận lời mời tham gia một không gian (là thành viên của không gian) hoặc có mối quan hệ thân thiết trước đó (chẳng hạn như nhật ký tương tác bằng tin nhắn trực tiếp) với người dùng gọi.
  • Hồ sơ ẩn danh: Nếu một người dùng được đề cập trong một không gian mà không phải là thành viên và không có mối quan hệ thân thiết trước đó với người dùng gọi, thì hồ sơ của người dùng đó vẫn ẩn danh. Đối với người dùng ẩn danh, isAnonymous là true và các thông tin chi tiết như displayName, email và avatarUrl sẽ bị bỏ qua. Tuy nhiên, đối với các yêu cầu API được thực hiện bằng xác thực ứng dụng, trường displayName luôn được điền sẵn.

Ví dụ về JSON sau đây cho thấy một tài nguyên User có thông tin chi tiết về hồ sơ được điền sẵn, trả về trong một phản hồi API hoặc sự kiện tương tác:

{
  "name": "users/12345678901234567890",
  "displayName": "Sasha",
  "domainId": "123abc",
  "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
  "email": "sasha@example.com",
  "type": "HUMAN",
  "isAnonymous": false
}

Ví dụ về JSON sau đây cho thấy một tài nguyên User ẩn danh, trong đó người gọi không thấy thông tin chi tiết về hồ sơ người dùng:

{
  "name": "users/10987654321098765432",
  "type": "HUMAN",
  "isAnonymous": true
}

Chỉ định một người dùng trong lệnh gọi đến Google Chat API

Để chỉ định một người dùng, hãy sử dụng các giá trị sau cho giá trị {user}:

  • Đối với người dùng trong tổ chức Google Workspace của bạn, hãy sử dụng một trong những cách tiếp cận sau:

    • name của tài nguyên User trong Chat API, chẳng hạn như users/123456789.
    • {person_id} cho tên của tài nguyên Person trong People API, trong đó resourceName là people/{person_id} – ví dụ: users/123456789 trong Chat API đại diện cho cùng một người với people/123456789 trong People API.
    • id cho tài nguyên User trong Directory API (ví dụ: users/123456789 trong Chat API) đại diện cho cùng một người với users/123456789 trong Directory API.
    • Đối với các yêu cầu API được thực hiện bằng xác thực người dùng, địa chỉ email của người dùng dưới dạng một biệt hiệu, ví dụ: users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com.

  • Đối với người dùng trong một tổ chức Google Workspace bên ngoài hoặc người dùng sử dụng Tài khoản Google, hãy sử dụng một trong những cách sau:

    • Email đại diện – ví dụ: users/EMAIL_USERNAME@WORKSPACE_DOMAIN.com hoặc users/EMAIL_USERNAME@gmail.com.
    • name chuẩn của tài nguyên User (chẳng hạn như users/12345678901234567890) nhận được từ một lệnh gọi API hoặc sự kiện tương tác trước đó.

Xác định người dùng từ một sự kiện tương tác hoặc phản hồi API

Bạn có thể xác định người dùng được trả về từ các lệnh gọi API hoặc sự kiện đến theo một số cách:

Vì Google Chat API điền sẵn thông tin hồ sơ cho cả người dùng nội bộ và bên ngoài khi sử dụng tính năng xác thực người dùng, nên nhà phát triển không cần gọi Directory API để phân giải tên hoặc email của các thành viên và người gửi tin nhắn.