Xác thực và uỷ quyền cho các ứng dụng trong Chat cũng như các yêu cầu API Google Chat

Xác thực và uỷ quyền là các cơ chế dùng để xác minh danh tính và quyền truy cập vào các tài nguyên tương ứng. Tài liệu này trình bày cách hoạt động của tính năng xác thực và uỷ quyền đối với ứng dụng Chat và yêu cầu API Chat.

Tổng quan về quy trình

Sơ đồ dưới đây cho thấy các bước xác thực và uỷ quyền cấp cao cho Google Chat:

Các bước nâng cao để xác thực và uỷ quyền trong Google Chat
Hình 1. Các bước nâng cao để xác thực và uỷ quyền trong Google Chat.

  1. Định cấu hình một dự án Google Cloud, bật API Chat và định cấu hình ứng dụng Chat: Trong quá trình phát triển, bạn tạo một dự án Google Cloud. Trong dự án Google Cloud, bạn cần bật API Chat, định cấu hình ứng dụng Chat và thiết lập tính năng xác thực. Để biết thêm thông tin, hãy xem các bài viết Phát triển trên Google WorkspaceTạo ứng dụng Chat.

  2. Gọi API Chat: Khi gọi API Chat, ứng dụng sẽ gửi thông tin xác thực đến API Chat. Nếu ứng dụng của bạn xác thực bằng tài khoản dịch vụ, thì thông tin xác thực sẽ được gửi trong mã của ứng dụng. Nếu yêu cầu gọi API Chat bằng phương thức xác thực của người dùng chưa được cấp, thì ứng dụng sẽ nhắc người dùng đăng nhập.

  3. Yêu cầu tài nguyên: Ứng dụng của bạn yêu cầu quyền truy cập thông qua các phạm vi mà bạn chỉ định trong khi thiết lập tính năng xác thực.

  4. Yêu cầu sự đồng ý: Nếu ứng dụng của bạn đang xác thực với tư cách người dùng, Google sẽ hiển thị màn hình xin phép bằng OAuth để người dùng có thể quyết định có cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu được yêu cầu hay không. Việc xác thực bằng tài khoản dịch vụ không yêu cầu sự đồng ý của người dùng.

  5. Gửi yêu cầu cấp tài nguyên đã được phê duyệt: Nếu người dùng đồng ý với các phạm vi uỷ quyền, ứng dụng sẽ gói thông tin xác thực và các phạm vi được người dùng phê duyệt vào một yêu cầu. Yêu cầu được gửi đến máy chủ uỷ quyền của Google để lấy mã truy cập.

  6. Google trả về một mã truy cập: Mã truy cập này chứa danh sách các phạm vi đã cấp. Nếu danh sách các phạm vi được trả về hạn chế hơn phạm vi yêu cầu, ứng dụng sẽ tắt mọi tính năng bị mã thông báo giới hạn.

  7. Quyền truy cập vào tài nguyên được yêu cầu: Ứng dụng của bạn sử dụng mã truy cập của Google để gọi API Chat và truy cập vào các tài nguyên của API Chat.

  8. Lấy mã làm mới (không bắt buộc): Nếu phải truy cập vào API Google Chat sau thời gian tồn tại của một mã truy cập, ứng dụng của bạn có thể nhận được mã làm mới. Để biết thêm thông tin, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập API Google.

  9. Yêu cầu thêm tài nguyên: Nếu cần thêm quyền truy cập, ứng dụng của bạn sẽ yêu cầu người dùng cấp phạm vi mới, dẫn đến một yêu cầu mới để nhận mã truy cập (bước 3-6).

Khi các ứng dụng trong Chat yêu cầu xác thực

Các ứng dụng trong Chat có thể gửi tin nhắn để phản hồi một hoạt động tương tác của người dùng hoặc gửi không đồng bộ. Họ cũng có thể thay mặt người dùng hoàn thành các thao tác, chẳng hạn như tạo phòng Chat hoặc xem danh sách người tham gia trong phòng Chat.

Các ứng dụng nhắn tin không yêu cầu xác thực để phản hồi hoạt động tương tác của người dùng, trừ phi ứng dụng Chat gọi API Chat hoặc một API khác của Google trong khi xử lý câu trả lời.

Để gửi tin nhắn không đồng bộ hoặc thực hiện thao tác thay cho người dùng, các ứng dụng trong Chat gửi yêu cầu RESTful đến API Chat. Yêu cầu này cần phải được xác thực và uỷ quyền.

Phản hồi hoạt động tương tác của người dùng không yêu cầu xác thực

Các ứng dụng Google Chat không cần xác thực với tư cách người dùng hoặc ứng dụng Chat để nhận và phản hồi đồng bộ với các sự kiện tương tác.

Các ứng dụng Google Chat sẽ nhận được sự kiện tương tác bất cứ khi nào người dùng tương tác hoặc gọi một ứng dụng, bao gồm:

  • Người dùng gửi tin nhắn cho ứng dụng nhắn tin.
  • Một người dùng đề cập đến một ứng dụng trong Chat bằng @.
  • Người dùng gọi một trong các lệnh dấu gạch chéo của ứng dụng Chat.

Sơ đồ dưới đây cho thấy trình tự phản hồi giữa một người dùng Chat và ứng dụng Chat:

Không cần được cho phép đối với các sự kiện tương tác với ứng dụng Chat
Hình 2.Sự kiện tương tác với ứng dụng Chat không yêu cầu xác thực.

  1. Người dùng gửi tin nhắn cho ứng dụng Chat trong Google Chat.
  2. Google Chat sẽ chuyển tiếp tin nhắn đến ứng dụng.
  3. Ứng dụng nhận tin nhắn, xử lý tin nhắn và trả về nội dung phản hồi cho Google Chat.
  4. Google Chat hiển thị câu trả lời cho người dùng hoặc trong một không gian.

Trình tự này lặp lại cho mỗi sự kiện tương tác với ứng dụng Chat.

Thư không đồng bộ yêu cầu xác thực

Tin nhắn không đồng bộ xảy ra khi ứng dụng Chat gửi yêu cầu đến API Chat, yêu cầu này đòi hỏi phải xác thực và uỷ quyền.

Khi gọi API Chat, các ứng dụng trong Chat có thể đăng tin nhắn lên Google Chat hoặc hoàn thành công việc và truy cập vào dữ liệu thay mặt người dùng. Ví dụ: sau khi phát hiện sự cố máy chủ ngừng hoạt động, ứng dụng Chat có thể gọi API Chat để:

  • Tạo một phòng Chat chuyên kiểm tra và khắc phục sự cố ngừng dịch vụ.
  • Thêm người khác vào phòng Chat.
  • Hãy đăng tin nhắn vào phòng Chat để cung cấp thông tin chi tiết về việc ngừng dịch vụ.

Sơ đồ dưới đây cho thấy trình tự tin nhắn không đồng bộ giữa một ứng dụng trong Chat và một phòng Chat:

Yêu cầu xác thực đối với thông báo không đồng bộ
Hình 3. Các thư không đồng bộ yêu cầu xác thực.

  1. Ứng dụng Chat tạo tin nhắn bằng cách gọi API Chat thông qua phương thức spaces.messages.create và đưa thông tin đăng nhập của người dùng vào yêu cầu HTTP.
  2. Google Chat xác thực ứng dụng Chat bằng tài khoản dịch vụ hoặc thông tin đăng nhập của người dùng.
  3. Google Chat hiển thị tin nhắn của ứng dụng đến một phòng Chat được chỉ định.

Phạm vi API Chat

Định cấu hình màn hình xin phép bằng OAuth và chọn phạm vi để xác định thông tin nào sẽ hiển thị cho người dùng và người đánh giá ứng dụng, đồng thời đăng ký ứng dụng của bạn để bạn có thể phát hành sau.

Để xác định cấp truy cập được cấp cho ứng dụng của mình, bạn cần xác định và khai báo phạm vi cấp quyền. Phạm vi uỷ quyền là một chuỗi URI OAuth 2.0 có chứa tên ứng dụng trên Google Workspace, loại dữ liệu mà ứng dụng này truy cập và cấp truy cập.

Phạm vi không nhạy cảm

Mã phạm vi Nội dung mô tả
https://www.googleapis.com/auth/chat.bot

Phạm vi chat.bot chỉ hỗ trợ tài khoản dịch vụ. Bạn không thể xác thực bằng thông tin đăng nhập của người dùng hoặc bằng tính năng uỷ quyền trên toàn miền thông qua phạm vi này.

Cho phép các ứng dụng trong Chat xem cuộc trò chuyện và gửi tin nhắn. Cấp quyền truy cập vào tất cả tính năng có trong các ứng dụng trong Chat.

Phạm vi nhạy cảm

Mã phạm vi Nội dung mô tả
https://www.googleapis.com/auth/chat.spaces Tạo cuộc trò chuyện và không gian cũng như xem hoặc cập nhật siêu dữ liệu (bao gồm cả chế độ cài đặt nhật ký) trong Chat.
https://www.googleapis.com/auth/chat.spaces.create Tạo cuộc trò chuyện mới trong Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Xem cuộc trò chuyện và các không gian trong ứng dụng Chat.
https://www.googleapis.com/auth/chat.memberships Xem, thêm và xoá thành viên khỏi các cuộc trò chuyện trong ứng dụng Chat.
https://www.googleapis.com/auth/chat.memberships.app Thêm và xoá chính ứng dụng khỏi các cuộc trò chuyện trong Google Chat.
https://www.googleapis.com/auth/chat.memberships.readonly Xem thành viên trong các cuộc trò chuyện trên Chat.
https://www.googleapis.com/auth/chat.messages.create Soạn và gửi tin nhắn trong Chat.
https://www.googleapis.com/auth/chat.messages.reactions Xem, thêm và xoá lượt thể hiện cảm xúc đối với tin nhắn trong Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create Thêm biểu tượng cảm xúc vào một tin nhắn trong Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Xem các lượt thể hiện cảm xúc đối với tin nhắn trong Chat.
https://www.googleapis.com/auth/chat.users.readstate Xem và sửa đổi dấu thời gian đọc lần gần đây nhất của cuộc trò chuyện trên Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Xem thời gian đọc gần đây nhất của cuộc trò chuyện trên Chat.

Phạm vi bị hạn chế

Mã phạm vi Nội dung mô tả
https://www.googleapis.com/auth/chat.delete Xoá các cuộc trò chuyện và không gian, đồng thời xoá quyền truy cập vào các tệp liên kết trong Chat.
https://www.googleapis.com/auth/chat.import Nhập không gian, tin nhắn và gói thành viên vào Chat. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat nhập dữ liệu
https://www.googleapis.com/auth/chat.messages Xem, soạn, gửi, cập nhật và xoá tin nhắn cũng như thêm, xem và xoá biểu tượng cảm xúc đối với tin nhắn.
https://www.googleapis.com/auth/chat.messages.readonly Xem tin nhắn và lượt thể hiện cảm xúc trong Chat.

Các phạm vi trong các bảng trước đó biểu thị mức độ nhạy cảm của các yếu tố này, theo các định nghĩa sau:

Nếu ứng dụng của bạn yêu cầu quyền truy cập vào bất kỳ API nào khác của Google, thì bạn cũng có thể thêm các phạm vi đó. Để biết thêm thông tin về các phạm vi API của Google, hãy xem phần Sử dụng OAuth 2.0 để truy cập API Google.

Để tìm hiểu thêm về phạm vi cho API Google Workspace, hãy xem bài viết Định cấu hình màn hình xin phép bằng OAuth và chọn phạm vi.

Loại xác thực bắt buộc

Có hai cách để ứng dụng trong Chat xác thực và uỷ quyền bằng API Chat: thông tin đăng nhập của người dùng hoặc tài khoản dịch vụ.

Với tính năng uỷ quyền thông tin xác thực người dùng, ứng dụng Chat có thể truy cập vào dữ liệu người dùng và hoàn tất các thao tác thay cho người dùng. Phạm vi OAuth chỉ định dữ liệu và hành động được phép.

Với uỷ quyền cho ứng dụng, ứng dụng Chat sẽ truy cập vào API dưới dạng ứng dụng bằng thông tin đăng nhập tài khoản dịch vụ. Tính năng uỷ quyền ứng dụng luôn sử dụng phạm vi uỷ quyền chat.bot.

Khi quyết định loại thông tin xác thực sẽ sử dụng cho một yêu cầu API cụ thể, hãy lưu ý rằng một số phương thức API chỉ hỗ trợ một loại thông tin xác thực cụ thể. Nếu một phương thức API hỗ trợ cả hai thông tin xác thực, thì loại thông tin xác thực dùng trong lệnh gọi sẽ ảnh hưởng đến kết quả được trả về:

  • Với sự uỷ quyền cho ứng dụng, các phương thức này chỉ trả về những tài nguyên mà ứng dụng có thể truy cập.
  • Khi được người dùng cho phép, các phương thức này chỉ trả về những tài nguyên mà người dùng có thể truy cập trong giao diện người dùng Chat.

Ví dụ: việc gọi phương thức ListSpaces có uỷ quyền cho ứng dụng sẽ trả về danh sách không gian chứa thành phần của ứng dụng. Việc gọi ListSpaces bằng lệnh uỷ quyền của người dùng sẽ trả về danh sách các không gian mà người dùng là thành viên. Trên thực tế, ứng dụng của bạn có thể sử dụng cả hai loại uỷ quyền khi gọi API Chat, tuỳ vào chức năng mà bạn muốn dùng.

Đối với các lệnh gọi API Chat không đồng bộ

Bảng sau đây liệt kê các phương thức API Chat và phạm vi uỷ quyền được hỗ trợ:

Phương thức Hỗ trợ Xác thực người dùng Hỗ trợ Xác thực ứng dụng Phạm vi uỷ quyền được hỗ trợ
Không gian  
Tạo không gian Bằng cách Xác thực người dùng:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Thiết lập không gian Bằng cách Xác thực người dùng:
  • chat.spaces.create
  • chat.spaces
Mua không gian Bằng cách Xác thực người dùng:
  • chat.spaces.readonly
  • chat.spaces
Với tính năng Xác thực ứng dụng:
  • chat.bot
Không gian danh sách Bằng cách Xác thực người dùng:
  • chat.spaces.readonly
  • chat.spaces
Với tính năng Xác thực ứng dụng:
  • chat.bot
Cập nhật không gian Bằng cách Xác thực người dùng:
  • chat.spaces
  • chat.import
Xoá không gian Bằng cách Xác thực người dùng:
  • chat.delete
  • chat.import
Hoàn tất quy trình nhập không gian Bằng cách Xác thực người dùng:
  • chat.import
Tìm tin nhắn trực tiếp Bằng cách Xác thực người dùng:
  • chat.spaces.readonly
  • chat.spaces
Với tính năng Xác thực ứng dụng:
  • chat.bot
Thành viên  
Tạo thành viên Bằng cách Xác thực người dùng:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Đăng ký hội viên Bằng cách Xác thực người dùng:
  • chat.memberships.readonly
  • chat.memberships
Với tính năng Xác thực ứng dụng:
  • chat.bot
Danh sách thành viên Bằng cách Xác thực người dùng:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Với tính năng Xác thực ứng dụng:
  • chat.bot
Xoá thành viên Bằng cách Xác thực người dùng:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Tin nhắn  
Tạo thông báo Bằng cách Xác thực người dùng:
  • chat.messages.create
  • chat.messages
  • chat.import
Với tính năng Xác thực ứng dụng:
  • chat.bot
Nhận thông báo Bằng cách Xác thực người dùng:
  • chat.messages.readonly
  • chat.messages
Với tính năng Xác thực ứng dụng:
  • chat.bot
Liệt kê các thông báo Bằng cách Xác thực người dùng:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Cập nhật thông báo Bằng cách Xác thực người dùng:
  • chat.messages
  • chat.import
Với tính năng Xác thực ứng dụng:
  • chat.bot
Xoá tin nhắn Bằng cách Xác thực người dùng:
  • chat.messages
  • chat.import
Với tính năng Xác thực ứng dụng:
  • chat.bot
Bày tỏ cảm xúc  
Tạo biểu tượng cảm xúc Bằng cách Xác thực người dùng:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Liệt kê biểu tượng cảm xúc Bằng cách Xác thực người dùng:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Xoá một lượt thể hiện cảm xúc Bằng cách Xác thực người dùng:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Nội dung đa phương tiện và tệp đính kèm  
Tải nội dung nghe nhìn lên dưới dạng tệp đính kèm Bằng cách Xác thực người dùng:
  • chat.messages.create
  • chat.messages
  • chat.import
Tải nội dung nghe nhìn xuống Bằng cách Xác thực người dùng:
  • chat.messages.readonly
  • chat.messages
Với tính năng Xác thực ứng dụng:
  • chat.bot
Nhận tệp đính kèm cho tin nhắn Với Xác thực ứng dụng:
  • chat.bot
Trạng thái đọc của người dùng
Xem trạng thái đọc không gian của người dùng Bằng cách Xác thực người dùng:
  • chat.users.readstate
  • chat.users.readstate.readonly
Cập nhật trạng thái đọc không gian của người dùng Bằng cách Xác thực người dùng:
  • chat.users.readstate
Nhận trạng thái đọc chuỗi thư của người dùng Bằng cách Xác thực người dùng:
  • chat.users.readstate
  • chat.users.readstate.readonly
Sự kiện không gian
Nhận sự kiện trong không gian Bằng cách Xác thực người dùng:
  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly
Liệt kê các sự kiện trong không gian Bằng cách Xác thực người dùng:
  • chat.messages
  • chat.messages.readonly
  • chat.messages.reactions
  • chat.messages.reactions.readonly
  • chat.memberships
  • chat.memberships.readonly
  • chat.spaces
  • chat.spaces.readonly

Đối với sự kiện tương tác với ứng dụng Chat

Bảng sau đây liệt kê những cách phổ biến mà người dùng tương tác với các ứng dụng trong Chat và việc xác thực là bắt buộc hay có hỗ trợ:

Trường hợp Không yêu cầu xác thực Hỗ trợ Xác thực người dùng Hỗ trợ Xác thực ứng dụng
Nhận tin nhắn từ:
Sự kiện tương tác với ứng dụng Chat
Lệnh gọi lại Apps Script
Google Cloud Pub/Sub
Trả lời tin nhắn:
Được đồng bộ, sử dụng một sự kiện tương tác với ứng dụng Chat
Đồng bộ, sử dụng giá trị trả về của lệnh gọi lại Apps Script
Gửi tin nhắn mới:
webhook đến