Mỗi ứng dụng Google Chat mà bạn tạo đều cần có dự án trên đám mây của Google Cloud riêng, trong đó Chat API được bật và định cấu hình.
Để thực hiện các lệnh gọi API chỉ có thể đọc bằng tính năng xác thực người dùng, chẳng hạn như lấy không gian và liệt kê tin nhắn, bạn chỉ cần bật API và tạo ứng dụng OAuth.
Để thực hiện các lệnh gọi API tạo, cập nhật và xoá, hoặc để triển khai và kiểm thử một ứng dụng Chat tương tác (được xây dựng dưới dạng tiện ích bổ sung của Google Workspace giúp mở rộng Chat), bạn cũng phải định cấu hình API Chat. Chế độ cài đặt cấu hình Chat API là nơi bạn chỉ định tất cả thông tin chi tiết về ứng dụng Chat, bao gồm cả tên hiển thị, hình đại diện, điểm cuối triển khai và các tính năng tương tác.
Điều kiện tiên quyết
- Tài khoản Google Workspace dành cho Doanh nghiệp hoặc Doanh nghiệp lớn có quyền truy cập vào Google Chat.
- Tạo một dự án trên Google Cloud.
- Định cấu hình màn hình xin phép bằng OAuth.
- Bật Google Chat API.
Chọn tên hiển thị, hình đại diện và nội dung mô tả cho ứng dụng Chat của bạn
Khi bật Chat API, bạn sẽ định cấu hình thông tin chi tiết về ứng dụng Chat mà người dùng nhìn thấy trong Chat, bao gồm tên hiển thị, hình đại diện và nội dung mô tả. Những thông tin này chỉ xuất hiện trong Chat. Để xuất bản ứng dụng Chat lên Marketplace, bạn cũng phải chỉ định thông tin chi tiết xuất hiện trong trang thông tin của ứng dụng Chat trên Marketplace.
Trước khi định cấu hình ứng dụng Chat, hãy chuẩn bị những thông tin sau:
| Trường | Mô tả | Định dạng |
|---|---|---|
| Tên ứng dụng | Tên hiển thị của ứng dụng Chat. | Tối đa 25 ký tự chữ-số |
| URL hình đại diện | Hình ảnh hiển thị dưới dạng hình đại diện của ứng dụng Chat. | Một URL loại HTTPS trỏ đến hình ảnh đồ hoạ hình vuông (PNG hoặc JPEG). Kích thước đề xuất là 256 x 256 pixel trở lên. |
| Mô tả | Nội dung mô tả ngắn về ứng dụng Chat, xuất hiện khi người dùng tìm ứng dụng trong Chat. | Tối đa 40 ký tự chữ-số |
| Nội dung mô tả dài | Không bắt buộc. Nội dung mô tả về những việc mà ứng dụng Chat có thể làm, xuất hiện khi người dùng bắt đầu cuộc trò chuyện với ứng dụng Chat hoặc mở trang chủ phiên cho một nhân viên hỗ trợ. Hiện chỉ được hỗ trợ khi cập nhật cấu hình ứng dụng bằng Google Cloud Console và không được hỗ trợ thông qua API tiện ích bổ sung của Google Workspace. | Tối đa 250 ký tự |
Tên, hình đại diện và nội dung mô tả của ứng dụng Chat sẽ xuất hiện cho người dùng trong giao diện người dùng của Chat. Đối với một số yêu cầu ghi của API Chat, Chat sử dụng thông tin này để ghi nhận các hành động mà ứng dụng Chat thực hiện trong Chat.
Ví dụ: nếu bạn gọi phương thức spaces.create(), Chat sẽ đưa tên của ứng dụng Chat vào phần mô tả về người đã tạo không gian, như trong hình sau:
spaces.create() được dùng để tạo
không gian thay mặt cho người dùng.
Để tương tác với ứng dụng Chat, người dùng cũng có thể xem hoặc sử dụng thông tin này theo những cách sau:
- @đề cập đến ứng dụng Chat để thêm ứng dụng đó vào không gian hoặc gửi tin nhắn cho ứng dụng đó.
- Tìm và bắt đầu một tin nhắn trực tiếp với ứng dụng Chat. Trong trình đơn Ứng dụng, tin nhắn trực tiếp sẽ hiển thị tên và hình đại diện của ứng dụng Chat.
- Trên thanh soạn tin, người dùng có thể duyệt xem các ứng dụng Chat và xem tên, hình đại diện cũng như nội dung mô tả của các ứng dụng đó.
Định cấu hình ứng dụng Chat trong Google Cloud Console
Khi bạn có thông tin chi tiết về ứng dụng Chat, hãy mở dự án trên Cloud và định cấu hình API Chat:
Trong Google Cloud Console, hãy chuyển đến trang Chat API rồi nhấp vào trang Configuration (Cấu hình):
Trong phần Application info (Thông tin ứng dụng), hãy điền vào các trường App name (Tên ứng dụng), Avatar URL (URL hình đại diện) và Description (Nội dung mô tả).
Không bắt buộc: Điền vào trường Nội dung mô tả dài.
Không bắt buộc: Trong trình đơn Cú pháp đánh dấu, hãy chọn cú pháp đánh dấu mặc định (Markdown hoặc Chat) cho tin nhắn của ứng dụng Chat. Để tìm hiểu thêm về định dạng văn bản và cách Chat xác định cú pháp đánh dấu cho các yêu cầu API, hãy xem bài viết Định dạng tin nhắn.
Trong phần Tính năng tương tác, hãy định cấu hình xem ứng dụng Chat của bạn có phản hồi các hoạt động tương tác của người dùng hay không:
Để tạo một ứng dụng Chat có tính tương tác, hãy bật chế độ Bật tính năng tương tác rồi hoàn tất các bước sau:
- Trong phần Chức năng:
- Không bắt buộc: Chọn Hỗ trợ Trang chủ ứng dụng để hiển thị thẻ trang chủ trong thẻ Trang chủ của tin nhắn trực tiếp 1:1 với ứng dụng Chat.
- Chọn Tham gia không gian và cuộc trò chuyện nhóm để người dùng có thể cài đặt và sử dụng ứng dụng Chat của bạn. Theo mặc định, người dùng có thể cài đặt và nhắn tin với ứng dụng Chat trong một không gian riêng giữa người dùng và ứng dụng Chat. Người dùng cũng có thể thêm và tương tác với ứng dụng Chat trong không gian có nhiều người.
Trong phần Cài đặt kết nối, hãy chọn cấu trúc mà bạn muốn dùng để nhận đối tượng sự kiện từ Chat:
- Để sử dụng dịch vụ HTTP, hãy chọn URL điểm cuối HTTP rồi cung cấp một URL.
- Để sử dụng một dự án Google Apps Script, hãy chọn Apps Script rồi cung cấp mã triển khai cho dự án đó.
- Để sử dụng một tác nhân Dialogflow, hãy chọn Dialogflow, chọn Dialogflow CX hoặc Dialogflow ES, rồi cung cấp tên tài nguyên của tác nhân.
- Để sử dụng Pub/Sub, hãy chọn Cloud Pub/Sub rồi nhập tên chủ đề.
Không bắt buộc: Để định tuyến đối tượng sự kiện đến các điểm cuối hoặc hàm cụ thể, hãy chuyển đến phần Cài đặt kết nối > Trình kích hoạt rồi cung cấp hoặc cập nhật các điểm cuối hoặc hàm gọi lại cho các Trình kích hoạt Chat sau:
- Trang chủ của ứng dụng (nếu bạn bật chế độ Hỗ trợ trang chủ của ứng dụng): Người dùng mở thẻ Trang chủ trong tin nhắn trực tiếp 1:1 bằng ứng dụng Chat.
- Đã thêm vào không gian: Người dùng thêm ứng dụng Chat vào một cuộc trò chuyện nhóm hoặc không gian, hoặc cài đặt ứng dụng Chat cho tin nhắn trực tiếp.
- Tin nhắn: Người dùng gửi tin nhắn đến ứng dụng Chat. Ví dụ: người dùng gửi tin nhắn trực tiếp đến ứng dụng Chat hoặc @đề_cập đến ứng dụng Chat trong một không gian có nhiều người.
- Đã xoá khỏi không gian: Người dùng gỡ cài đặt hoặc xoá ứng dụng Chat khỏi không gian.
- Lệnh trong ứng dụng: Người dùng gọi một lệnh nhanh, lệnh dấu gạch chéo hoặc hành động tin nhắn từ ứng dụng Chat.
Không bắt buộc: Thêm các tính năng tương tác khác như phiên, câu lệnh mở đầu, lệnh (lệnh nhanh, lệnh dấu gạch chéo, và hành động đối với tin nhắn) hoặc bản xem trước đường liên kết.
Trong phần Chế độ hiển thị, hãy chọn Cung cấp ứng dụng Chat này cho một số người và nhóm rồi nhập địa chỉ email của các cá nhân hoặc Nhóm Google trong tổ chức Google Workspace của bạn:
- Để tự cài đặt và kiểm thử ứng dụng, hãy nhập địa chỉ email của riêng bạn.
- Để chia sẻ ứng dụng Chat nội bộ với một nhóm hoặc toàn bộ tổ chức mà không cần xuất bản lên Marketplace, hãy nhập một hoặc nhiều nhóm trên Google Groups. Nhóm không có giới hạn về số lượng thành viên. Nếu ứng dụng của bạn yêu cầu phạm vi
chat.app.*, bạn vẫn phải xuất bản ứng dụng để quản trị viên phê duyệt. - Nếu quản trị viên của bạn hạn chế việc cài đặt ứng dụng trên Marketplace đối với các ứng dụng trong danh sách cho phép, thì Google Cloud Console sẽ giới hạn trường này ở 5 địa chỉ email của người dùng cá nhân cho mục đích phát triển. Chế độ hiển thị của nhóm chỉ áp dụng sau khi quản trị viên thêm ứng dụng vào danh sách cho phép.
- Trong phần Chức năng:
Không bắt buộc: Trong phần Nhật ký, hãy chọn hộp đánh dấu Ghi lỗi vào Logging để sử dụng Google Cloud Logging. Để biết thêm thông tin, hãy xem bài viết Truy vấn nhật ký lỗi cho ứng dụng Chat.
Nhấp vào Lưu.
Sau khi bạn lưu cấu hình, bất kỳ ai mà bạn chỉ định trong chế độ cài đặt Chế độ hiển thị của API Chat đều có thể cài đặt, thử nghiệm hoặc sử dụng ứng dụng Chat. Để bắt đầu thử nghiệm và gỡ lỗi ứng dụng Chat, hãy xem bài viết Thử nghiệm các tính năng tương tác cho ứng dụng Google Chat.
Định cấu hình ứng dụng Chat bằng Google Cloud CLI
Thay vì sử dụng Google Cloud Console, bạn có thể xem và cập nhật cấu hình của một ứng dụng Chat từ dòng lệnh bằng Google Cloud CLI (gcloud CLI). Ví dụ: bạn có thể định cấu hình một ứng dụng Chat từ một tập lệnh hoặc lưu cấu hình của ứng dụng đó trong một tệp mà bạn lưu trữ cùng với mã của mình.
Nhóm lệnh gcloud beta workspace-add-ons chat-app-config có các lệnh sau:
describe: Hiện cấu hình.update: Định cấu hình ứng dụng Chat lần đầu tiên hoặc thay đổi cấu hình của ứng dụng.
Các lệnh này sử dụng tài nguyên chatAppConfig trong API Tiện ích bổ sung của Google Workspace.
Trước khi bắt đầu
- Cài đặt Giao diện dòng lệnh (CLI) gcloud. Nếu bạn đã cài đặt CLI gcloud trước đó, hãy đảm bảo rằng bạn có phiên bản mới nhất bằng cách chạy
gcloud components update. Đăng nhập vào gcloud CLI bằng tài khoản người dùng của bạn. Các lệnh này không hỗ trợ tài khoản dịch vụ.
gcloud auth loginĐặt dự án trên đám mây của ứng dụng Chat làm dự án mặc định của gcloud CLI. Sử dụng mã dự án vì các lệnh không chấp nhận số dự án.
gcloud config set project PROJECT_IDNgoài ra, hãy thêm cờ
--projectvào mỗi lệnh.Bật API Tiện ích bổ sung của Google Workspace trong dự án trên đám mây:
gcloud services enable gsuiteaddons.googleapis.comĐảm bảo rằng bạn có các vai trò Quản lý danh tính và quyền truy cập (IAM) sau đây trên dự án trên đám mây:
- Nhà phát triển tiện ích bổ sung của Google Workspace
(
roles/gsuiteaddons.developer) để xem và cập nhật cấu hình, hoặc Người đọc tiện ích bổ sung của Google Workspace (roles/gsuiteaddons.reader) để chỉ xem cấu hình. Các vai trò này bao gồm các quyền được liệt kê trong phần Điều kiện tiên quyết và xác thực. - Người dùng sử dụng dịch vụ
(
roles/serviceusage.serviceUsageConsumer). Giao diện dòng lệnh gcloud sử dụng dự án trên đám mây làm dự án hạn mức cho các yêu cầu của mình, điều này yêu cầu quyềnserviceusage.services.use.
Vai trò Chủ sở hữu và Người chỉnh sửa có tất cả các quyền này. Vai trò Chủ sở hữu ứng dụng Chat và Người xem ứng dụng Chat (cấp quyền truy cập vào trang cấu hình trong Google Cloud Console) là chưa đủ.
- Nhà phát triển tiện ích bổ sung của Google Workspace
(
Xem cấu hình
Để xem cấu hình của ứng dụng Chat, hãy chạy lệnh describe:
gcloud beta workspace-add-ons chat-app-config describeKết quả sẽ tương tự như sau:
avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
allowlistedTestingPrincipals:
- user@example.com
appCommands:
- command: /help
commandId: 1
commandType: SLASH_COMMAND
description: Show available commands
connectionConfig:
httpEndpointConfig:
commonUrl: https://example.com/chat
supportsMultiuserSpaces: true
urlPatterns:
- hostPattern: example.com
pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE
Nếu dự án trên đám mây chưa có ứng dụng Chat, thì lệnh này sẽ thành công và chỉ in trường name của cấu hình:
name: projects/123456789012/chatAppConfig
Để thay đổi kết quả, hãy thêm một trong các cờ sau:
--format=json: In cấu hình ở định dạng JSON.--view=basic: Bỏ qua chế độ cài đặt tính năng tương tác (interactiveFeatureConfig).--format="value(displayName)": Chỉ in tên hiển thị hoặc một dòng trống nếu dự án trên đám mây chưa có ứng dụng Chat. Ứng dụng Chat đã định cấu hình luôn có tên hiển thị, vì vậy, bạn có thể sử dụng cờ này trong tập lệnh để kiểm tra xem ứng dụng Chat có tồn tại hay không.
Cập nhật cấu hình
Để định cấu hình ứng dụng Chat lần đầu tiên hoặc để thay đổi cấu hình của ứng dụng, hãy chạy lệnh update. Chỉ định chế độ cài đặt bằng cờ hoặc trong tệp cấu hình. Bạn không thể kết hợp cả hai trong một lệnh.
Lần đầu tiên chạy lệnh cho một dự án trên đám mây, bạn phải chỉ định ít nhất một tên hiển thị và một nội dung mô tả. Trừ phi bạn đặt trạng thái thành đã tắt, ứng dụng Chat sẽ hoạt động ngay khi lệnh kết thúc. Sau đó, những người mà bạn liệt kê là người kiểm thử có thể tìm và sử dụng ứng dụng đó.
Sử dụng cờ
Ví dụ sau đây định cấu hình một ứng dụng Chat nhận sự kiện tại một điểm cuối HTTP:
gcloud beta workspace-add-ons chat-app-config update \
--display-name="Quickstart App" \
--description="Quickstart app" \
--avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
--http-endpoint-url=HTTP_ENDPOINT_URL \
--supports-multiuser-spaces \
--add-allowlisted-testing-principals=USER_EMAIL \
--error-logging-enabledThay thế nội dung sau:
HTTP_ENDPOINT_URL: URL loại HTTPS nhận đối tượng sự kiện từ Chat.USER_EMAIL: địa chỉ email của một người hoặc một nhóm trong tổ chức Google Workspace của bạn có thể cài đặt và kiểm thử ứng dụng Chat, chẳng hạn như địa chỉ email của chính bạn.
Lệnh này sẽ in cấu hình đã cập nhật.
Bảng sau đây liệt kê các cờ cho chế độ cài đặt trên trang Cấu hình của API Chat trong Google Cloud Console. Để biết thông tin chi tiết về từng cờ, hãy xem tài liệu tham khảo về lệnh update.
| Chế độ cài đặt trong Google Cloud Console | Cờ |
|---|---|
| Tên ứng dụng | --display-name |
| URL hình đại diện | --avatar-uri bằng URL loại HTTPS của một hình ảnh đáp ứng
các yêu cầu về hình đại diện, hoặc
--clear-avatar-uri để sử dụng hình đại diện mặc định |
| Mô tả | --description |
| Trạng thái ứng dụng | --state=active hoặc --state=disabled |
| Cú pháp đánh dấu | --markup-syntax=markdown hoặc
--markup-syntax=chat |
| Tham gia không gian và cuộc trò chuyện nhóm | --supports-multiuser-spaces hoặc
--no-supports-multiuser-spaces |
| Chế độ cài đặt kết nối | Một trong những mã sau:
|
| Chế độ hiển thị | --add-allowlisted-testing-principals,
--remove-allowlisted-testing-principals và
--clear-allowlisted-testing-principals |
| Ghi lỗi vào Logging | --error-logging-enabled hoặc
--no-error-logging-enabled |
Lệnh, bản xem trước đường liên kết và các điểm cuối riêng biệt cho mỗi điều kiện kích hoạt không có cờ. Để định cấu hình các chế độ này, hãy sử dụng tệp cấu hình.
Ví dụ: để tắt ứng dụng Chat mà không thay đổi các chế độ cài đặt khác, hãy chạy lệnh sau. Để bật lại, hãy dùng --state=active.
gcloud beta workspace-add-ons chat-app-config update --state=disabledSử dụng tệp cấu hình
Để lưu cấu hình trong một tệp hoặc để định cấu hình các chế độ cài đặt không có cờ, hãy truyền tệp YAML hoặc JSON đến lệnh update. Tệp này sử dụng các trường của tài nguyên chatAppConfig, đây cũng là các trường mà lệnh describe in ra.
Tạo một tệp chứa các chế độ cài đặt cần cập nhật. Ví dụ: tạo một tệp có tên
chat_app_config.yamlvới nội dung sau:displayName: Cymbal Assistant description: Helps manage tasks and schedules avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png state: ACTIVE errorLoggingEnabled: true interactiveFeatureConfig: supportsMultiuserSpaces: true connectionConfig: httpEndpointConfig: commonUrl: https://example.com/chat appCommands: - commandId: 1 commandType: SLASH_COMMAND command: /help description: Show available commands urlPatterns: - hostPattern: example.com pathPrefix: tasks/ allowlistedTestingPrincipals: - USER_EMAILThay thế
USER_EMAILbằng địa chỉ email của một người hoặc một nhóm trong tổ chức Google Workspace của bạn, những người có thể cài đặt và thử nghiệm ứng dụng Chat.Chạy lệnh
updatebằng cờ--config-file:gcloud beta workspace-add-ons chat-app-config update \ --config-file=chat_app_config.yaml
Để bắt đầu từ cấu hình hiện tại của một ứng dụng Chat, hãy lưu kết quả của lệnh describe vào một tệp:
gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yamlSau đó, hãy chỉnh sửa tệp, xoá các trường mà bạn không muốn thay đổi và chuyển tệp đó đến lệnh update. Nếu tệp chứa một chế độ cài đặt mà lệnh không thể cập nhật, thì lệnh sẽ không thành công. Để biết thông tin chi tiết, hãy xem phần Các điểm hạn chế.
Lệnh update bỏ qua trường name trong tệp. Tệp này luôn cập nhật dự án trên đám mây mà bạn đặt trong gcloud CLI, vì vậy, bạn có thể sử dụng cùng một tệp để định cấu hình ứng dụng Chat trong một dự án khác trên đám mây.
Cách lệnh áp dụng các thay đổi của bạn
- Chỉ những chế độ cài đặt mà bạn chỉ định mới thay đổi. Với cờ, lệnh này sẽ thay đổi chế độ cài đặt cho các cờ mà bạn truyền. Với tệp cấu hình, nó sẽ thay đổi các trường có trong tệp, vì vậy tệp không cần phải chứa toàn bộ cấu hình. Chế độ cài đặt kết nối là một ngoại lệ: loại kết nối mà bạn đặt sẽ thay thế loại kết nối hiện tại và phiên bản Dialogflow mà bạn đặt sẽ thay thế toàn bộ cấu hình Dialogflow.
- Danh sách được thay thế toàn bộ. Nếu tệp chứa trường
appCommands,urlPatternshoặcallowlistedTestingPrincipals, thì danh sách trong tệp sẽ thay thế danh sách hiện tại. Để thêm hoặc xoá từng người kiểm thử, hãy sử dụng cờ--add-allowlisted-testing-principalsvà--remove-allowlisted-testing-principals. - Giá trị trống sẽ xoá một chế độ cài đặt. Ví dụ: một tệp chứa
urlPatterns: []tronginteractiveFeatureConfigsẽ xoá tất cả mẫu URL xem trước đường liên kết. - Lệnh không thành công sẽ không thay đổi bất cứ điều gì. Nếu một giá trị không hợp lệ, lệnh này sẽ in lỗi và giữ nguyên cấu hình.
- Các yêu cầu bị giới hạn tần suất. API giới hạn số lượng yêu cầu đọc và yêu cầu cập nhật mỗi phút cho từng dự án trên đám mây và cho từng tổ chức. Mỗi lệnh
updatesẽ gửi một yêu cầu cập nhật. Nếu bạn thêm hoặc xoá người kiểm thử bằng cờ, thì lệnh này cũng sẽ gửi yêu cầu đọc. Để thay đổi một số chế độ cài đặt, hãy truyền các chế độ cài đặt đó trong một lệnh hoặc một tệp thay vì chạy một lệnh cho mỗi chế độ cài đặt.
Các điểm hạn chế
- Các lệnh này chỉ hỗ trợ những ứng dụng Chat được xây dựng dưới dạng tiện ích bổ sung của Google Workspace.
- Các lệnh này không hỗ trợ tài khoản dịch vụ hoặc việc mạo danh tài khoản dịch vụ. Bạn phải đăng nhập vào gcloud CLI bằng tài khoản người dùng.
- Một dự án trên đám mây có một cấu hình ứng dụng Chat và các lệnh không thể xoá cấu hình đó. Để ngăn mọi người sử dụng ứng dụng Chat, hãy đặt trạng thái của ứng dụng thành đã tắt hoặc xoá dự án trên đám mây.
- Bản cập nhật sẽ áp dụng cho ứng dụng Chat đang hoạt động. Các lệnh không có chế độ nháp hoặc chạy thử.
- Khi một ứng dụng Chat được xuất bản hoặc đang được xem xét trong Google Workspace Marketplace, các lệnh không thể thay đổi tên hiển thị, hình đại diện, nội dung mô tả, lệnh hoặc mẫu URL xem trước đường liên kết của ứng dụng đó.
- Các lệnh này hỗ trợ chế độ cài đặt trong tài nguyên
chatAppConfig. Để định cấu hình một chế độ cài đặt mà tài nguyên không có, hãy sử dụng Google Cloud Console.
Khắc phục sự cố
Nếu một lệnh không thành công, hãy tìm văn bản trong thông báo lỗi trong bảng sau. Nếu thông báo bắt đầu bằng một trạng thái như INVALID_ARGUMENT, thì API Tiện ích bổ sung của Google Workspace đã từ chối yêu cầu và văn bản sau trạng thái sẽ mô tả vấn đề.
| Thông báo lỗi chứa | Nguyên nhân | Giải pháp |
|---|---|---|
Invalid choice: 'chat-app-config' hoặc
Invalid choice: 'workspace-add-ons' |
Lệnh này không bao gồm beta hoặc phiên bản gcloud CLI của bạn không bao gồm các lệnh này. |
Bắt đầu lệnh bằng gcloud beta workspace-add-ons chat-app-config. Nếu lỗi vẫn tiếp diễn, hãy cập nhật gcloud CLI lên phiên bản mới nhất. |
PROJECT ID |
Dự án được đặt thành một số dự án. | Đặt dự án thành mã dự án. |
Failed to parse value(s) in protobuf |
Tệp cấu hình chứa một trường mà gcloud CLI không nhận dạng được. Thông báo lỗi sẽ nêu tên trường. | So sánh tên trường với kết quả của lệnh describe. Nếu trường này là trường mới, hãy cập nhật gcloud CLI lên phiên bản mới nhất. |
does not have permission to access projects instance |
API đã từ chối yêu cầu. Văn bản sau thông báo này cho biết lý do. Ví dụ:
|
Kiểm tra các yêu cầu trong phần Trước khi bắt đầu. |
INVALID_ARGUMENT |
Một giá trị không hợp lệ. Ví dụ: tên hiển thị phải có từ 3 đến 25 ký tự và nội dung mô tả phải có từ 1 đến 40 ký tự. Nếu thông báo có chứa not found or deleted, thì mã dự án không chính xác. |
Sửa giá trị mà thông báo lỗi mô tả rồi chạy lại lệnh. |
FAILED_PRECONDITION |
Ứng dụng Chat không cho phép yêu cầu này. Ví dụ: tiện ích bổ sung không được tạo dưới dạng tiện ích bổ sung của Google Workspace hoặc được xuất bản trong Google Workspace Marketplace và bạn không thể thay đổi chế độ cài đặt. | Làm theo hướng dẫn trong thông báo lỗi. Để định cấu hình một ứng dụng Chat không phải là tiện ích bổ sung của Google Workspace, hãy sử dụng Google Cloud Console hoặc chuyển đổi ứng dụng đó. |
RESOURCE_EXHAUSTED hoặc 429 |
API đã nhận được quá nhiều yêu cầu cho dự án trên đám mây hoặc cho tổ chức của bạn trong một khoảng thời gian ngắn. | Hãy đợi một phút rồi chạy lại lệnh. |
Định cấu hình ứng dụng Chat bằng API tiện ích bổ sung của Google Workspace
Thay vì định cấu hình ứng dụng Chat theo cách thủ công trong Google Cloud Console, bạn có thể đọc và cập nhật cấu hình cho một ứng dụng Chat được xây dựng dưới dạng tiện ích bổ sung của Google Workspace theo phương thức lập trình bằng cách sử dụng tài nguyên chatAppConfig trong Google Workspace add-ons API.
chatAppConfig là một tài nguyên đơn lẻ luôn tồn tại cho mỗi dự án trên đám mây. Trước khi bạn lưu cấu hình lần đầu tiên, tài nguyên sẽ chứa một cấu hình trống (đây cũng là nội dung mà GetChatAppConfig trả về nếu bạn đọc tài nguyên trước lần lưu đầu tiên). Vì tài nguyên đã tồn tại nên bạn không cần tạo riêng tài nguyên đó. Hãy sử dụng UpdateChatAppConfig để lưu cấu hình ban đầu và cập nhật cấu hình hiện có.
Điều kiện tiên quyết và xác thực
Trước khi gọi GetChatAppConfig hoặc UpdateChatAppConfig, hãy hoàn tất các điều kiện tiên quyết sau:
- Bật API tiện ích bổ sung Google Workspace (
gsuiteaddons.googleapis.com) trong dự án trên đám mây của bạn. Nếu muốn, bạn có thể bật Google Chat API (chat.googleapis.com) nếu muốn xem hoặc cập nhật cấu hình của ứng dụng Chat trong Google Cloud Console hoặc gọi Google Chat API. - Xác thực với tư cách là người dùng bằng thông tin xác thực OAuth 2.0 bao gồm phạm vi
https://www.googleapis.com/auth/cloud-platform. Phương thức xác thực tài khoản dịch vụ không được hỗ trợ cho các phương thứcchatAppConfig. - Đảm bảo người dùng đã xác thực có các quyền cần thiết về Quản lý danh tính và quyền truy cập (IAM) đối với dự án trên đám mây mục tiêu:
gsuiteaddons.chatAppConfigs.getvàchat.bots.getđể đọc cấu hình (GetChatAppConfig).gsuiteaddons.chatAppConfigs.update,chat.bots.updatevàchat.bots.getđể cập nhật cấu hình (UpdateChatAppConfig).
- Nếu bạn sử dụng thư viện ứng dụng, hãy cài đặt phiên bản mới nhất của thư viện ứng dụng API tiện ích bổ sung của Google Workspace cho ngôn ngữ của bạn. Để xem danh sách thư viện ứng dụng, hãy xem Tài liệu tham khảo API tiện ích bổ sung của Google Workspace.
Cập nhật cấu hình ứng dụng Chat
Để định cấu hình ứng dụng Chat lần đầu tiên hoặc cập nhật một cấu hình hiện có, hãy gửi yêu cầu PATCH (UpdateChatAppConfig) đến tài nguyên singleton chatAppConfig cho dự án trên đám mây của bạn:
- Để lưu lần đầu trên một dự án trên đám mây có
chatAppConfigtrống, bạn cần códisplayName(3 đến 25 ký tự) vàdescription(1 đến 40 ký tự). Nếu bạn bỏ quainteractiveFeatureConfigtrong lần lưu đầu tiên, ứng dụng Chat sẽ được định cấu hình là không tương tác. - Đối với các bản cập nhật tiếp theo, hãy sử dụng tham số truy vấn
updateMaskkhông bắt buộc để chỉ định các trường được phân tách bằng dấu phẩy cần cập nhật (hoặc bỏ quaupdateMaskđể cập nhật tất cả các trường được cung cấp). Việc cập nhật một trường lặp lại (appCommands,urlPatternshoặcallowlistedTestingPrincipals) sẽ thay thế toàn bộ danh sách.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"name": "projects/PROJECT_NUMBER/chatAppConfig",
"displayName": "Cymbal Assistant",
"description": "Helps manage tasks and schedules",
"avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
"state": "ACTIVE",
"errorLoggingEnabled": true,
"markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
"interactiveFeatureConfig": {
"supportsMultiuserSpaces": false,
"connectionConfig": {
"httpEndpointConfig": {
"commonUrl": "https://example.com/chat"
}
},
"appCommands": [
{
"commandType": "SLASH_COMMAND",
"commandId": 1,
"command": "/help",
"description": "Show available commands",
"dialogEnabled": false
}
],
"urlPatterns": [
{
"hostPattern": "example.com",
"pathPrefix": "tasks/"
}
],
"allowlistedTestingPrincipals": [
"USER_EMAIL"
]
}
}
Thay thế các thông tin sau trong URL, tiêu đề và nội dung của yêu cầu:
PROJECT_NUMBER: Số dự án dạng số của dự án trên đám mây lưu trữ ứng dụng Chat của bạn.ACCESS_TOKEN: Mã truy cập OAuth 2.0 của người dùng được uỷ quyền với phạm vihttps://www.googleapis.com/auth/cloud-platform.USER_EMAIL: Địa chỉ email hoặc Nhóm Google trong tổ chức Google Workspace của bạn để đưa vào danh sách cho phép nhằm thử nghiệm ứng dụng Chat (ví dụ: địa chỉ email của chính bạn).- Các trường cấu hình mẫu trong nội dung yêu cầu (chẳng hạn như
displayName,description,avatarUrivàinteractiveFeatureConfig, bao gồm cả cấu hình điểm cuối, lệnh, mẫu URL xem trước đường liên kết và đối tượng kiểm thử) bằng các giá trị cho ứng dụng Chat của bạn. Để biết thông tin chi tiết về tất cả các trường và tuỳ chọn điểm cuối được hỗ trợ, hãy xem tài liệu tham khảo về RESTprojects.chatAppConfigvàprojects.chatAppConfig.patch.
Lấy cấu hình ứng dụng Chat
Để đọc cấu hình ứng dụng Chat hiện tại cho một dự án trên đám mây, hãy gọi phương thức GetChatAppConfig.
Bạn có thể truyền tham số truy vấn view không bắt buộc (ChatAppConfigView):
BASIC(mặc định): Trả về siêu dữ liệu cơ bản mà không cóinteractiveFeatureConfig.FULL: Trả về tất cả các trường cấu hình, bao gồm cảinteractiveFeatureConfig.
Nếu cấu hình ứng dụng Chat chưa được lưu cho dự án trên đám mây, thì phương thức này sẽ trả về một đối tượng ChatAppConfig trống.
HTTP
GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN
Node.js
const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;
const client = new GSuiteAddOnsClient();
async function getChatAppConfig() {
const [response] = await client.getChatAppConfig({
name: 'projects/PROJECT_NUMBER/chatAppConfig',
view: 'FULL',
});
console.log(JSON.stringify(response, null, 2));
}
getChatAppConfig();
Python
from google.cloud import gsuiteaddons_v1
client = gsuiteaddons_v1.GSuiteAddOnsClient()
request = gsuiteaddons_v1.GetChatAppConfigRequest(
name="projects/PROJECT_NUMBER/chatAppConfig",
view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)
Hạn mức sử dụng
Các phương thức chatAppConfig có hạn mức theo từng dự án. Nếu bạn vượt quá hạn mức, yêu cầu sẽ không thành công và trả về mã trạng thái HTTP 429: Too many requests. Để biết hạn mức, hãy xem bài viết Hạn mức sử dụng API tiện ích bổ sung của Google Workspace.
Khắc phục lỗi
Nếu yêu cầu chatAppConfig không thành công, hãy kiểm tra mã trạng thái HTTP và trường message trong phản hồi lỗi. Bảng sau đây liệt kê các lỗi thường gặp, nguyên nhân và cách giải quyết.
| Mã trạng thái HTTP | Nguyên nhân thường gặp | Độ phân giải |
|---|---|---|
400: Bad Request (INVALID_ARGUMENT) |
|
Kiểm tra trường message để tìm trường không hợp lệ và sửa yêu cầu. Để biết các trường và giá trị được hỗ trợ, hãy xem
projects.chatAppConfig
tài liệu tham khảo. |
400: Bad Request (FAILED_PRECONDITION) |
|
|
403: Forbidden (PERMISSION_DENIED) |
|
|
404: Not Found (NOT_FOUND) |
Dự án trên đám mây trong tên tài nguyên không tồn tại hoặc người dùng đã xác thực không thể truy cập vào dự án đó. | Kiểm tra để đảm bảo rằng tên tài nguyên sử dụng đúng số dự án theo định dạng projects/PROJECT_NUMBER/chatAppConfig và người dùng có quyền truy cập vào dự án trên đám mây. |
429: Too Many Requests (RESOURCE_EXHAUSTED) |
Đã vượt quá hạn mức cho mỗi dự án. | Hãy đợi và thử gửi lại yêu cầu sau. Để biết các giới hạn, hãy xem phần Giới hạn sử dụng. |
Những điều cần lưu ý đối với các tiện ích bổ sung hiện có của Google Workspace
Ứng dụng Chat yêu cầu cấu hình khác so với các tiện ích bổ sung của Google Workspace giúp mở rộng các ứng dụng khác của Google Workspace. Nếu tiện ích bổ sung của bạn mở rộng các ứng dụng khác của Google Workspace, hãy cân nhắc các yêu cầu sau để định cấu hình ứng dụng Chat:
- Cả cá nhân và quản trị viên Google Workspace đều phải cài đặt được tiện ích bổ sung của bạn từ Marketplace. Bạn định cấu hình các chế độ cài đặt này trong SDK của Marketplace.
- Ứng dụng Chat không sử dụng tên và biểu trưng mà bạn định cấu hình cho các ứng dụng khác của Google Workspace trong đối tượng
addons.commoncủa tệp kê khai. - Đối với các tiện ích bổ sung được xuất bản lên Google Workspace Marketplace, bạn không thể lưu bản nháp của bất kỳ thay đổi nào đối với chế độ cài đặt cấu hình của Google Chat API. Sau khi bạn cập nhật và lưu chế độ cài đặt cấu hình API Chat, ứng dụng Chat đã cập nhật sẽ ngay lập tức được cung cấp cho tất cả người dùng hiện tại. Để cập nhật trang thông tin của bạn trên Marketplace, bạn có thể tạo bản nháp trước khi gửi mọi thay đổi.
- Nếu bạn tạo tiện ích bổ sung bằng Apps Script:
- Bạn phải sử dụng cùng một mã triển khai Apps Script mà bạn dùng cho phần còn lại của cấu hình tiện ích bổ sung.
- Bạn không thể sử dụng trình chỉnh sửa Apps Script để cài đặt bản triển khai thử nghiệm trong Chat. Thay vào đó, bạn phải cài đặt trực tiếp từ giao diện người dùng của Chat.
- Nếu bạn xây dựng tiện ích bổ sung bằng dịch vụ HTTP, hãy bỏ qua mọi thông tin chi tiết về cấu hình ứng dụng Chat trong tệp kê khai
projects.deploymentsmà bạn tạo bằng API tiện ích bổ sung của Google Workspace. Các bản triển khai HTTP mà bạn chỉ định trong SDK Google Workspace Marketplace chỉ được dùng cho các ứng dụng khác của Google Workspace. Thay vào đó, hãy định cấu hình ứng dụng Chat trong Google Cloud Console, bằng gcloud CLI hoặc sử dụng tài nguyênchatAppConfigtrong API Tiện ích bổ sung của Google Workspace.
Cấp cho người khác quyền định cấu hình API Chat
Bạn có thể cấp cho một số người dùng quyền truy cập vào trang cấu hình ứng dụng Chat bằng cách cấp cho họ vai trò Quản lý danh tính và quyền truy cập (IAM) trên Google Cloud là Chủ sở hữu ứng dụng Chat hoặc Người xem ứng dụng Chat. Người dùng có các vai trò này không thể điều hướng đến trang cấu hình ứng dụng Chat bằng cách sử dụng trang tổng quan API và dịch vụ, nhưng có thể truy cập vào trang cấu hình bằng cách điều hướng đến Google Cloud Console cho dự án trên đám mây lưu trữ ứng dụng Chat như sau:
https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID
Trong đó, PROJECT_ID là mã dự án của dự án trên Google Cloud lưu trữ ứng dụng Chat.
Chủ đề có liên quan
- Chọn cấu trúc ứng dụng Chat
- Nhận và phản hồi các hoạt động tương tác của người dùng
- Thử nghiệm các tính năng tương tác cho ứng dụng Google Chat
Ứng dụng Chat không phải là tiện ích bổ sung: Định cấu hình Google Chat API
Nếu bạn duy trì một ứng dụng Chat không phải là tiện ích bổ sung của Google Workspace, thì cấu hình của bạn sẽ sử dụng một điểm cuối duy nhất cho tất cả sự kiện tương tác thay vì trình kích hoạt theo sự kiện:
Trong Google Cloud Console, hãy chuyển đến trang Cấu hình của Chat API:
Trong phần Tính năng tương tác, hãy bật chế độ Bật tính năng tương tác.
Xoá Xây dựng ứng dụng Chat này dưới dạng tiện ích bổ sung của Google Workspace. Một hộp thoại sẽ mở ra để yêu cầu bạn xác nhận. Trong hộp thoại, hãy nhấp vào Tắt.
Trong phần Chức năng, hãy chọn Hỗ trợ Trang chủ ứng dụng hoặc Tham gia không gian và cuộc trò chuyện nhóm nếu cần.
Trong phần Cài đặt kết nối, hãy chỉ định một điểm cuối duy nhất cho ứng dụng Chat (URL điểm cuối HTTP, mã triển khai Apps Script, tên chủ đề Cloud Pub/Sub, hoặc Dialogflow).
Định cấu hình các mục không bắt buộc như Lệnh, Câu lệnh mở đầu, Bản xem trước đường liên kết, Chế độ hiển thị và Nhật ký, sau đó nhấp vào Lưu.
Để nâng cấp một ứng dụng Chat không phải là tiện ích bổ sung thành một tiện ích bổ sung của Google Workspace giúp mở rộng Google Chat, hãy xem bài viết Chuyển đổi ứng dụng Google Chat thành tiện ích bổ sung của Google Workspace.