Kết nối ứng dụng Chat với các dịch vụ và công cụ khác

Trang này mô tả cách kết nối một ứng dụng Google Chat với một dịch vụ hoặc công cụ bên ngoài Google Chat. Mặc dù các ứng dụng Chat có thể hoạt động hiệu quả, nhưng chúng thường phối hợp với các hệ thống khác và yêu cầu các ứng dụng đồng hành kết nối tài khoản, cho phép truy cập dữ liệu, hiển thị dữ liệu bổ sung hoặc định cấu hình lựa chọn ưu tiên của người dùng.

Để xác thực người dùng bằng dịch vụ bên thứ ba hoặc quy trình OAuth, ứng dụng Chat của bạn sẽ thực hiện các bước sau:

  1. Phát hiện thời điểm cần có uỷ quyền hoặc cấu hình.
  2. Trả về thẻ uỷ quyền cơ bản nhắc người dùng đăng nhập hoặc định cấu hình dịch vụ.
  3. Chuyển hướng đến URI hoàn tất để Google Chat tự động thử lại lượt tương tác ban đầu sau khi người dùng hoàn tất việc uỷ quyền.

Cấu trúc về cách các ứng dụng Google Chat xác thực với một dịch vụ bên thứ ba.

Điều kiện tiên quyết

HTTP

Một ứng dụng Google Chat nhận và phản hồi tương tác của người dùng. Để tạo một ứng dụng, hãy hoàn tất hướng dẫn bắt đầu nhanh về HTTP.

Apps Script

Một ứng dụng Google Chat nhận và phản hồi tương tác của người dùng. Để tạo một ứng dụng, hãy hoàn tất hướng dẫn bắt đầu nhanh về Apps Script.

Phát hiện rằng cần có uỷ quyền

Khi tương tác với ứng dụng Chat, người dùng có thể không được phép truy cập vào một tài nguyên được bảo vệ vì nhiều lý do, chẳng hạn như:

  • Mã truy cập để kết nối với dịch vụ bên thứ ba chưa được tạo hoặc đã hết hạn.
  • Mã truy cập không bao gồm tài nguyên được yêu cầu.
  • Mã truy cập không bao gồm các phạm vi bắt buộc của yêu cầu.

Ứng dụng Chat của bạn phải phát hiện những trường hợp này để người dùng có thể đăng nhập và uỷ quyền truy cập vào dịch vụ của bạn.

Nếu đang xây dựng trong Apps Script, bạn có thể dùng thư viện OAuth2 cho Google Apps Script (hoặc phiên bản OAuth1), trong đó hàm hasAccess sẽ kiểm tra xem người dùng đã uỷ quyền truy cập vào một dịch vụ hay chưa. Ngoài ra, khi sử dụng các yêu cầu UrlFetchApp.fetch, bạn có thể đặt tham số muteHttpExceptions thành true để kiểm tra mã phản hồi và nội dung trong đối tượng HttpResponse được trả về.

Nhắc người dùng bằng thẻ uỷ quyền cơ bản

Khi ứng dụng Chat của bạn phát hiện thấy cần có uỷ quyền hoặc cấu hình, hãy trả về một phản hồi AuthorizationError để hiển thị thẻ uỷ quyền cơ bản riêng tư cho người dùng.

Hình ảnh sau đây minh hoạ ví dụ về thẻ uỷ quyền cơ bản của Google:

Lời nhắc uỷ quyền cơ bản cho Tài khoản ví dụ.
Hình 1: Lời nhắc uỷ quyền cơ bản cho Tài khoản ví dụ. Lời nhắc cho biết ứng dụng Chat muốn hiển thị thêm thông tin nhưng cần được người dùng phê duyệt để truy cập vào tài khoản.

Để nhắc người dùng bằng thẻ uỷ quyền cơ bản, hãy trả về một đối tượng AuthorizationError:

HTTP

Trả về phản hồi JSON sau đây:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Thay thế nội dung sau:

  • AUTHORIZATION_URL: URL loại HTTPS cho ứng dụng web xử lý việc xác thực, uỷ quyền hoặc định cấu hình.
  • RESOURCE_DISPLAY_NAME: Tên hiển thị của tài nguyên hoặc dịch vụ được bảo vệ. Tên này sẽ xuất hiện cho người dùng trên lời nhắc uỷ quyền. Ví dụ: nếu RESOURCE_DISPLAY_NAME của bạn là Example Account, thì lời nhắc sẽ cho biết rằng ứng dụng cần được phê duyệt để truy cập vào Example Account của bạn.

Hoàn tất yêu cầu định cấu hình

Trong Chat, người dùng có thể hoàn tất quy trình uỷ quyền và Chat sẽ tự động thử lại hoạt động tương tác ban đầu mà không cần làm mới theo cách thủ công. Chat hỗ trợ tính năng tự động thử lại nếu trigger (điều kiện kích hoạt) là Message (Tin nhắn), Added to space (Được thêm vào không gian) hoặc App command (Lệnh ứng dụng).

Đối với những điều kiện kích hoạt này, ứng dụng Chat của bạn sẽ nhận được một URI chuyển hướng hoàn tất (configCompleteRedirectUri / completeRedirectUri) trong tải trọng sự kiện:

  • Thông báo: chat.messagePayload.configCompleteRedirectUri
  • Đã thêm vào không gian: chat.addedToSpacePayload.configCompleteRedirectUri
  • Lệnh ứng dụng: chat.appCommandPayload.configCompleteRedirectUri

Bạn phải mã hoá URI chuyển hướng này trong <var>AUTHORIZATION_URL</var> và chuyển hướng trình duyệt của người dùng đến URI này sau khi quy trình uỷ quyền hoàn tất. Việc chuyển hướng đến URL này báo hiệu cho Google Chat rằng yêu cầu uỷ quyền hoặc yêu cầu cấu hình đã được thực hiện.

Khi người dùng được chuyển hướng thành công đến URI chuyển hướng hoàn tất được cung cấp trong tải trọng sự kiện ban đầu, Google Chat sẽ thực hiện các bước sau:

  1. Xoá lời nhắc uỷ quyền riêng tư xuất hiện cho người dùng khởi tạo.
  2. Chuyển tin nhắn ban đầu sang chế độ công khai để các thành viên khác trong không gian có thể nhìn thấy.
  3. Gửi đối tượng sự kiện ban đầu đến ứng dụng Chat của bạn lần thứ hai.

Nếu bạn không chuyển hướng đến URI chuyển hướng hoàn tất, người dùng vẫn có thể hoàn tất quy trình uỷ quyền, nhưng Google Chat sẽ không tự động thử lại lần thực thi trước đó và người dùng phải gọi lại ứng dụng Chat của bạn theo cách thủ công.

Việc truy cập vào URI chuyển hướng hoàn tất chỉ ảnh hưởng đến một lượt tương tác duy nhất của người dùng. Nếu người dùng đã nhắn tin nhiều lần cho một ứng dụng Chat và nhận được nhiều lời nhắc, thì việc hoàn tất quy trình xác thực và định cấu hình cho một lời nhắc sẽ chỉ thử lại tương tác cụ thể đó.

Xác thực người dùng Chat bên ngoài Chat

Khi liên kết đến một URL bên ngoài Chat (chẳng hạn như lệnh gọi lại web OAuth), bạn thường cần tương quan phiên web bên ngoài với danh tính người dùng trong Chat. Bạn nên bảo vệ ứng dụng web đích bằng tính năng Đăng nhập bằng Google.

Sử dụng mã thông báo nhận dạng được phát hành trong quá trình đăng nhập để lấy mã nhận dạng người dùng. Thông tin xác nhận sub chứa mã nhận dạng duy nhất của người dùng trên Google và có thể tương quan với tên tài nguyên người dùng (chat.user.name) trên Google Chat.

Để liên kết yêu cầu sub với tên tài nguyên users/{user} của Google Chat, hãy thêm users/ vào trước giá trị yêu cầu sub. Ví dụ: giá trị yêu cầu sub là 123 sẽ tương ứng với users/123 trong các đối tượng sự kiện được gửi đến ứng dụng Chat của bạn.

Mã mẫu

Các mẫu mã sau đây minh hoạ cách một ứng dụng Chat có thể yêu cầu thông tin đăng nhập OAuth2 khi không có mạng bằng cách sử dụng thẻ uỷ quyền cơ bản, lưu trữ thông tin đăng nhập đó trong cơ sở dữ liệu, chuyển hướng đến URI hoàn tất và thực hiện các lệnh gọi API bằng xác thực người dùng:

Ứng dụng trò chuyện không phải là tiện ích bổ sung: Kết nối một ứng dụng trò chuyện với các dịch vụ và công cụ khác

Nếu bạn duy trì một ứng dụng Chat không phải là tiện ích bổ sung Google Workspace, thì ứng dụng Chat của bạn sẽ yêu cầu cấu hình bằng cách sử dụng actionResponse thuộc loại REQUEST_CONFIG và đọc configCompleteRedirectUrl từ đối tượng Event cấp cao nhất.

Để nâng cấp một ứng dụng Chat không phải là tiện ích bổ sung lên khung tiện ích bổ sung của Google Workspace, hãy xem phần Chuyển đổi ứng dụng Google Chat thành tiện ích bổ sung của Google Workspace.

Yêu cầu người dùng thiết lập trong một ứng dụng Chat không phải là tiện ích bổ sung

Trong một ứng dụng Chat không phải là tiện ích bổ sung, hãy trả về URL cấu hình cho người dùng ở dạng sau:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

Lệnh này yêu cầu Google Chat đưa ra một lời nhắc riêng tư cho người dùng, trong đó CONFIGURATION_URL là một đường liên kết để người dùng truy cập nhằm xác thực, uỷ quyền hoặc định cấu hình thêm. Phản hồi REQUEST_CONFIG không thể kết hợp với thông báo phản hồi thông thường; mọi văn bản, thẻ hoặc thuộc tính khác đều bị bỏ qua.

Hoàn tất yêu cầu định cấu hình trong một ứng dụng Chat không phải là tiện ích bổ sung

Mọi hoạt động tương tác MESSAGE, ADDED_TO_SPACE và APP_COMMAND Event mà một ứng dụng Chat không phải là tiện ích bổ sung nhận được đều bao gồm trường cấp cao nhất configCompleteRedirectUrl. Mã hoá URL này trong URL cấu hình và chuyển hướng người dùng đến URL đó sau khi hoàn tất để Google Chat xoá câu lệnh, chuyển đổi tin nhắn gốc thành tin nhắn công khai và gửi lại sự kiện tương tác ban đầu đến ứng dụng Chat của bạn.

Để xem các mẫu triển khai, hãy xem mẫu ứng dụng kết nối Node.js và mẫu ứng dụng xác thực Python MyProfile trên GitHub.