Nếu bạn đã tạo và xuất bản một ứng dụng Google Chat sử dụng các sự kiện tương tác của Google Chat API, chẳng hạn như một ứng dụng dựa trên hướng dẫn bắt đầu nhanh về ứng dụng Google Chat, thì trang này sẽ hướng dẫn cách chuyển đổi ứng dụng đó thành một tiện ích bổ sung Google Workspace mở rộng Google Chat.
Bằng cách chuyển đổi, ứng dụng Google Chat của bạn có thể sử dụng khung tiện ích bổ sung của Google Workspace, mở ra những khả năng mới để tích hợp và sử dụng các tính năng trong Google Chat và trên Google Workspace. Ví dụ: thay vì có 2 bản phân phối (một ứng dụng Google Chat và một tiện ích bổ sung của Google Workspace), bạn có thể phân phối một tiện ích bổ sung duy nhất của Google Workspace thông qua Google Workspace Marketplace. Tiện ích bổ sung này sẽ mở rộng các ứng dụng Chat cùng với các ứng dụng lưu trữ khác của Google Workspace, chẳng hạn như Gmail, Lịch và Tài liệu.
Các điểm hạn chế
Trước khi bắt đầu chuyển đổi, hãy xem Các hạn chế của tiện ích bổ sung Google Workspace mở rộng Google Chat để đảm bảo ứng dụng Google Chat của bạn có thể được chuyển đổi mà không làm mất chức năng thiết yếu.
Bước 1: Sao chép mã ứng dụng Google Chat hiện có
Quá trình chuyển đổi yêu cầu bạn phải thay đổi mã. Để tránh ảnh hưởng đến ứng dụng Google Chat đang hoạt động, hãy tạo và xử lý bản sao mã của bạn.
Apps Script
- Mở dự án Google Apps Script hiện có của bạn trong ứng dụng Google Chat.
- Ở bên trái, hãy nhấp vào Tổng quan .
- Ở bên phải, hãy nhấp vào biểu tượng Tạo bản sao .
- Ở bên trái, hãy nhấp vào Cài đặt dự án .
- Trong phần Dự án trên Google Cloud, hãy nhấp vào Thay đổi dự án.
- Nhập số dự án giống với số dự án được liên kết với dự án ứng dụng Google Chat hiện có của bạn.
- Nhấp vào Đặt dự án.
HTTP
Tạo một nhánh hoặc bản sao của cơ sở mã hiện có và triển khai cơ sở mã đó dưới dạng một dịch vụ mới, tách biệt với ứng dụng Google Chat đang hoạt động.
Nếu ứng dụng của bạn được triển khai trên Google Cloud và dựa vào các tính năng gắn liền với dự án Google Cloud (ví dụ: danh tính App Engine mặc định), thì mã mới phải được triển khai trên một dịch vụ được liên kết với dự án ứng dụng Google Chat hiện có.
Bước 2: Sửa đổi mã đã sao chép
Các tiện ích bổ sung của Google Workspace mở rộng Google Chat sử dụng các cấu trúc yêu cầu và phản hồi khác nhau so với các ứng dụng Google Chat được tạo bằng các sự kiện tương tác Chat API. Bạn cần cập nhật mã để sử dụng tiện ích bổ sung Google Workspace EventObject thay vì Event của Google Chat API cho các yêu cầu và phản hồi.
Hãy sử dụng Hướng dẫn chuyển đổi mã để sửa đổi mã của bạn.
Bước 3: Bật cấu hình tiện ích bổ sung Google Workspace cho người dùng thử nghiệm
Sử dụng bảng điều khiển Google Cloud để định cấu hình chế độ cài đặt tiện ích bổ sung của Google Workspace cho ứng dụng Google Chat:
Chuyển đến trang cấu hình API Google Chat trong bảng điều khiển Google Cloud.
Trong mục Tính năng tương tác, hãy nhấp vào Chuyển đổi thành tiện ích bổ sung.
Bật chế độ Bật chế độ cài đặt cấu hình tiện ích bổ sung.
Trong phần Chế độ hiển thị, hãy thêm địa chỉ email của người dùng thử nghiệm.
Nếu cần, hãy cập nhật Connection Settings (Chế độ cài đặt kết nối) bằng URL điểm cuối triển khai hoặc mã nhận dạng triển khai Apps Script của mã ứng dụng Google Chat mà bạn đã sao chép và sửa đổi ở Bước 2.
Nhấp vào Lưu và kiểm thử.
Bước 4: Kiểm thử ứng dụng đã chuyển đổi
Kiểm thử kỹ lưỡng chức năng của tiện ích bổ sung Google Workspace bằng tài khoản người dùng thử nghiệm mà bạn đã định cấu hình ở Bước 3. Xác minh tất cả các tính năng và hoạt động tương tác.
Bước 5: Hoàn tất quá trình chuyển đổi cho tất cả người dùng
Sau khi xác minh rằng tiện ích bổ sung đã chuyển đổi của Google Workspace hoạt động chính xác, bạn có thể cung cấp tiện ích đó cho tất cả người dùng.
Chuyển đến trang cấu hình API Google Chat trong bảng điều khiển Google Cloud.
Trong mục Tính năng tương tác, hãy nhấp vào Chuyển đổi thành tiện ích bổ sung. Một bảng điều khiển bên sẽ mở ra.
Trong bảng điều khiển bên, hãy nhấp vào Chuyển đổi thành tiện ích bổ sung.
Nhập mã dự án rồi nhấp vào Chuyển đổi.
Ứng dụng Google Chat hiện là một tiện ích bổ sung của Google Workspace, giúp mở rộng Google Chat.
Không bắt buộc: Dọn dẹp hoặc giải phóng các tài nguyên Google Cloud không dùng đến
Nếu muốn, sau khi chuyển đổi ứng dụng Google Chat thành một tiện ích bổ sung Google Workspace, để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với những tài nguyên mà ứng dụng Google Chat đã dùng nhưng không còn được sử dụng nữa, hãy cân nhắc tắt các tài nguyên đó.
Hướng dẫn chuyển đổi mã
Phần này trình bày chi tiết mối liên kết giữa định dạng tương tác Event của Google Chat API và định dạng EventObject của tiện ích bổ sung Google Workspace.
Ánh xạ yêu cầu
Bảng sau đây cho biết cách các trường trong API Google Chat Event liên kết đến các trường tương ứng trong tiện ích bổ sung Google Workspace EventObject.
Trường Event tương tác của API Google Chat |
Trường EventObject tiện ích bổ sung của Google Workspace |
Ghi chú |
|---|---|---|
action.actionMethodName |
Không áp dụng | Đối với các lượt tương tác với thẻ, tên phương thức có thể được truyền dưới dạng một tham số trong commonEventObject.parameters. Xem phần Mở hộp thoại ban đầu. |
action.parameters |
commonEventObject.parameters |
|
appCommandMetadata |
chat.appCommandPayload.appCommandMetadata |
|
common |
commonEventObject |
|
configCompleteRedirectUrl |
|
Có trong nhiều tải trọng tuỳ thuộc vào loại sự kiện. |
dialogEventType |
|
Có trong nhiều tải trọng tuỳ thuộc vào loại sự kiện. |
eventTime |
chat.eventTime |
|
isDialogEvent |
|
Có trong nhiều tải trọng tuỳ thuộc vào loại sự kiện. |
message |
|
Có trong nhiều tải trọng tuỳ thuộc vào loại sự kiện. |
space |
|
|
thread |
|
Có trong nhiều tải trọng tuỳ thuộc vào loại sự kiện. |
threadKey |
|
Có trong nhiều tải trọng tuỳ thuộc vào loại sự kiện. |
token |
Không áp dụng | Quy trình xác minh được xử lý theo cách khác, hãy xem phần Yêu cầu xác minh cho ứng dụng HTTP. |
type |
Không áp dụng | Bạn có thể suy ra loại sự kiện từ trình kích hoạt. |
user |
chat.user |
Yêu cầu lập bản đồ theo trường hợp sử dụng
Bảng sau đây cho thấy sự khác biệt về tải trọng yêu cầu cho các trường hợp sử dụng phổ biến giữa các ứng dụng Google Chat được tạo bằng các sự kiện tương tác Chat API và các tiện ích bổ sung Google Workspace mở rộng Google Chat.
| Trường hợp sử dụng | Tải trọng tương tác Event Chat API |
Tải trọng EventObject của tiện ích bổ sung Google Workspace |
|---|---|---|
| Đã thêm ứng dụng vào không gian | { "type": "ADDED_TO_SPACE", "space": { ... } } |
{ "chat": { "addedToSpacePayload": { "space": { ... } } } } |
| Xoá ứng dụng khỏi không gian | { "type": "REMOVED_FROM_SPACE", "space": { ... } } |
{ "chat": { "removedFromSpacePayload": { "space": { ... } } } } |
| Người dùng @đề cập đến một ứng dụng | { "type": "MESSAGE", "message": { ... }, "space": { ... }, "configCompleteRedirectUrl": "..." } |
{ "chat": { "messagePayload": { "message": { ... }, "space": { ... }, "configCompleteRedirectUri": "..." } } } |
| Người dùng @đề cập đến một ứng dụng để thêm ứng dụng đó vào không gian | Bạn cần xử lý một yêu cầu từ Google Chat:{ "type": "ADDED_TO_SPACE", "space": { ... }, "message": { ... } } |
Bạn phải xử lý 2 yêu cầu từ Google Chat. Yêu cầu đầu tiên: { "chat": { "addedToSpacePayload": { "space": { ... }, "interactionAdd": true } } } Yêu cầu thứ hai: { "chat": { "messagePayload": { "message": { ... }, "space": { ... } } } } |
| Lệnh dấu gạch chéo | { "type": "MESSAGE", "message": { "slashCommand": { ... } }, "space": { ... } } |
{ "chat": { "appCommandPayload": { "message": { ... }, "space": { ... }, "appCommandMetadata": { ... } } } } |
| Lệnh dấu gạch chéo để thêm ứng dụng vào không gian | Bạn cần xử lý một yêu cầu từ Google Chat:{ "type": "ADDED_TO_SPACE", "space": { ... }, "message": { "slashCommand": { ... } } } |
Bạn phải xử lý 2 yêu cầu từ Google Chat. Yêu cầu đầu tiên: { "chat": { "addedToSpacePayload": { "space": { ... }, "interactionAdd": true } } } Yêu cầu thứ hai: { "chat": { "appCommandPayload": { "message": { ... }, "space": { ... }, "appCommandMetadata": { ... } } } } |
| Người dùng nhấp vào một nút trên thẻ hoặc hộp thoại | { "type": "CARD_CLICKED", "common": { ... }, "space": { ... }, "message": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } Đối với các sự kiện hộp thoại, { "type": "CARD_CLICKED", "common": { "formInputs": { "contactName": { "": { "stringInputs": { "value": ["Kai 0"] }} } } }, "space": { ... }, "message": { ... }, "isDialogEvent": true, "dialogEventType": "..." } |
{ "commonEventObject": { ... }, "chat": { "buttonClickedPayload": { "message": { ... }, "space": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } } } Đối với các sự kiện hộp thoại, { "commonEventObject": { "formInputs": { "contactName": { "stringInputs": { "value": ["Kai 0"] } } } }, "chat": { "buttonClickedPayload": { "message": { ... }, "space": { ... }, "isDialogEvent": "true", "dialogEventType": "..." } } } |
| Người dùng gửi thông tin trong thẻ trang chủ của ứng dụng | { "type": "SUBMIT_FORM", "common": { ... }, "space": { ... }, "message": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } |
{ "commonEventObject": { ... }, "chat": { "buttonClickedPayload": { "message": { ... }, "space": { ... }, "isDialogEvent": "...", "dialogEventType": "SUBMIT_DIALOG" } } } |
| Người dùng gọi một lệnh trong ứng dụng bằng lệnh nhanh | { "type": "APP_COMMAND", "space": { ... }, "isDialogEvent": "...", "dialogEventType": "..." } |
{ "chat": { "appCommandPayload": { "message": { ... }, "space": { ... }, "appCommandMetadata": { ... } } } } |
| Liên kết xem trước | { "type": "MESSAGE", "message": { "matchedUrl": "..." }, "space": { ... } } |
{ "chat": { "messagePayload": { "message": { "matchedUrl": "..." }, "space": { ... } } } } |
| Người dùng cập nhật một tiện ích trong thông báo hoặc hộp thoại dạng thẻ | { "type": "WIDGET_UPDATED", "space": { ... }, "common": { ... } } |
{ "commonEventObject": { ... }, "chat": { "widgetUpdatedPayload": { "space": { ... } } } } |
Ánh xạ phản hồi theo trường hợp sử dụng
Các tiện ích bổ sung của Google Workspace mở rộng Google Chat sẽ trả về các thao tác thay vì một đối tượng Message. Bảng sau đây liên kết các loại phản hồi Message của Google Chat API với các thao tác tương ứng của tiện ích bổ sung Google Workspace.
| Trường hợp sử dụng | Phản hồi của API Google Chat Message |
Phản hồi thao tác Chat của tiện ích bổ sung Google Workspace |
|---|---|---|
| Tạo tin nhắn trong không gian được gọi | { "actionResponse": { "type": "NEW_MESSAGE" }, "text": "..." }
|
{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": { "text": "..." } } } } } Để tìm hiểu thêm, hãy xem phần Gửi tin nhắn. |
| Cập nhật tin nhắn | { "actionResponse": { "type": "UPDATE_MESSAGE" }, "text": "..." } Để tìm hiểu thêm, hãy xem bài viết Chỉnh sửa tin nhắn (Chat). |
{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": { "message": { "text": "..." } } } } } Để tìm hiểu thêm, hãy xem bài viết Cập nhật tin nhắn (tiện ích bổ sung). |
| Liên kết xem trước | { "actionResponse": { "type": "UPDATE_USER_MESSAGE_CARDS" }, "cardsV2": [{ ... }] } Để tìm hiểu thêm, hãy xem phần Xem trước đường liên kết (Chat). |
{ "hostAppDataAction": { "chatDataAction": { "updateInlinePreviewAction": { "cardsV2": [{ ... }] } } } } Để tìm hiểu thêm, hãy xem phần Xem trước đường liên kết(tiện ích bổ sung). |
| Mở một hộp thoại ban đầu | { "actionResponse": { "type": "DIALOG", "dialogAction": { "dialog": { "body": { /* Card object */ } } } } } Để tìm hiểu thêm, hãy xem phần Mở hộp thoại (Chat). |
{ "action": { "navigations": [{ "pushCard": { /* Card object */ } }] } } Thẻ mà bạn đẩy có thể chứa các tiện ích có onClick hành động. Đối với tiện ích bổ sung Google Workspace HTTP, hãy định cấu hình các thao tác này để gọi một điểm cuối hàm: { "onClick": { "action": { "function": "https://...", "parameters": [{ "key": "clickedButton", "value": "submit" }] } } } Để tìm hiểu thêm, hãy xem bài viết Mở hộp thoại (tiện ích bổ sung). |
| Đóng hộp thoại | { "actionResponse": { "type": "DIALOG", "dialogAction": { "actionStatus": { "userFacingMessage": "..." } } } } Để tìm hiểu thêm, hãy xem phần Đóng hộp thoại (Chat). |
{ "action": { "navigations": [{ "endNavigation": "CLOSE_DIALOG" }], "notification": { "text": "..."} } } Để tìm hiểu thêm, hãy xem bài viết Đóng hộp thoại (tiện ích bổ sung). |
| Kết nối với hệ thống bên ngoài (Yêu cầu cấu hình) | { "actionResponse": { "type": "REQUEST_CONFIG", "url": "..." } } Để tìm hiểu thêm, hãy xem phần Kết nối với hệ thống bên ngoài. |
{ "basic_authorization_prompt": { "authorization_url": "...", "resource": "..." } } Để tìm hiểu thêm, hãy xem bài viết Kết nối tiện ích bổ sung Google Workspace với dịch vụ bên thứ ba. |
| Các mục tự động hoàn thành trên tiện ích tương tác | { "actionResponse": { "type": "UPDATE_WIDGET", "updatedWidget": { "suggestions": { "items": ["..."] }, "widget": "widget_id" } } } Để tìm hiểu thêm, hãy xem phần Thêm trình đơn chọn nhiều mục. |
{ "action": { "modifyOperations": [{ "updateWidget": { "widgetId": "widget_id", "selectionInputWidgetSuggestions": { "suggestions": ["..."] } } }] } } Để tìm hiểu thêm, hãy xem bài viết Thu thập và xử lý thông tin của người dùng Google Chat. |
Xử lý các lượt tương tác với thẻ trên những thông báo được tạo trước khi chuyển đổi
Khi bạn chuyển đổi một ứng dụng Google Chat dựa trên HTTP thành một tiện ích bổ sung của Google Workspace, các hoạt động tương tác trên thẻ trong những tin nhắn được tạo trước khi chuyển đổi sẽ cần được xử lý đặc biệt. Tiện ích bổ sung Google Workspace sử dụng URL HTTP đầy đủ cho action.function của thẻ, trong khi các ứng dụng Google Chat được tạo bằng sự kiện tương tác Google Chat API sử dụng tên hàm. Bảng sau đây tóm tắt những điểm khác biệt này.
| Ứng dụng Google Chat được xây dựng bằng các sự kiện tương tác của Google Chat API | Tiện ích bổ sung của Google Workspace giúp mở rộng Google Chat | |
|---|---|---|
| Cấu hình | Bạn định cấu hình một điểm cuối duy nhất cho tất cả sự kiện trong bảng điều khiển Google Cloud. Khi triển khai các hoạt động tương tác với thẻ, action của thẻ chỉ chứa tên của hàm cần thực thi. Điểm cuối HTTP chung được gọi cho các sự kiện lượt nhấp vào thẻ.
Để tìm hiểu thêm, hãy xem phần Mở hộp thoại (Chat). { "onClick": { "action": { "function": "submit" } } } |
Bạn có thể tuỳ ý định cấu hình các điểm cuối cho mỗi sự kiện trong bảng điều khiển Google Cloud, nhưng không bao gồm các sự kiện nhấp vào thẻ. Khi triển khai các lượt tương tác với thẻ, action của thẻ phải chứa URL đầy đủ của điểm cuối HTTP để gọi. Bạn có thể đặt một điểm cuối HTTP riêng biệt cho mỗi nút hoặc sử dụng một điểm cuối chung và truyền thao tác dưới dạng một tham số trong action.parameters.
Để tìm hiểu thêm, hãy xem bài viết Mở hộp thoại (tiện ích bổ sung). { "onClick": { "action": { "function": "https://...", "parameters": [{ "key": "method", "value": "submit" }] } } } |
Để đảm bảo các lượt tương tác với thẻ hoạt động đối với những tin nhắn được tạo trước lượt chuyển đổi, hãy định cấu hình URL tương tác với thẻ trên trang cấu hình Google Chat API.
URL này chỉ được dùng cho các lượt tương tác trên những thông báo được tạo trước khi bạn chuyển đổi ứng dụng. Khi người dùng tương tác với một trong những thông báo này, giá trị action.function ban đầu sẽ được truyền dưới dạng một tham số có tên là __action_method_name__.
Ví dụ: Lượt nhấp vào thẻ
Nếu bạn đã định cấu hình URL tương tác của thẻ là https://.../card-interaction-handler và người dùng nhấp vào một thẻ trong tin nhắn cũ với thao tác sau:
{
"onClick": {
"action": {
"function": "submit"
}
}
}
Một sự kiện sẽ được gửi đến URL tương tác với thẻ mà bạn đã định cấu hình theo định dạng sau:
{
"commonEventObject": {
"parameters": {
"__action_method_name__": "submit"
}
},
"chat": {
"buttonClickedPayload": { ... }
}
}
Ví dụ: Trình đơn nhiều lựa chọn
Nếu người dùng tương tác với một trình đơn chọn nhiều mục có nguồn dữ liệu bên ngoài:
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"externalDataSource": {
"function": "getContacts"
}
}
}
Một sự kiện sẽ được gửi đến URL tương tác với thẻ mà bạn đã định cấu hình theo định dạng sau:
{
"commonEventObject": {
"parameters": {
"__action_method_name__": "getContacts",
}
},
"chat": {
"widgetUpdatedPayload": { ... }
}
}
Nếu bạn bật chế độ Sử dụng URL điểm cuối HTTP chung cho tất cả các điều kiện kích hoạt cho các điều kiện kích hoạt HTTP, thì URL chung cũng được dùng cho các sự kiện Đã nhấp vào nút.
Xác minh các yêu cầu đối với tiện ích bổ sung HTTP của Google Workspace mở rộng Chat
Đối với các ứng dụng Google Chat dựa trên HTTP, bạn cần cập nhật logic để xác minh rằng các yêu cầu bắt nguồn từ Google khi chuyển đổi sang tiện ích bổ sung Google Workspace.
- Xác minh ứng dụng Google Chat HTTP cho sự kiện tương tác Google Chat API: Xác minh yêu cầu của Google Chat
- Xác minh HTTP của tiện ích bổ sung Google Workspace: Xác minh yêu cầu của Google
Sau đây là những điểm khác biệt chính trong quy trình xác minh yêu cầu:
| Loại ứng dụng | Đối tượng được hỗ trợ | Email tài khoản dịch vụ |
|---|---|---|
| Ứng dụng Google Chat được xây dựng bằng các sự kiện tương tác của Google Chat API | Số hiệu dự án | chat@system.gserviceaccount.com |
| Tiện ích bổ sung của Google Workspace mở rộng Google Chat | Chỉ điểm cuối HTTP | Email tài khoản dịch vụ cho mỗi dự án |
Bạn có thể tìm thấy địa chỉ email duy nhất của tài khoản dịch vụ cho tiện ích bổ sung Google Workspace trong phần Chuyển đổi sang tiện ích bổ sung Google Workspace trên trang cấu hình Google Chat API trong bảng điều khiển Google Cloud.
Cách xác minh yêu cầu trong tiện ích bổ sung Google Workspace đã nâng cấp:
- Nếu sử dụng các hàm Cloud Run, hãy cấp vai trò
roles/cloudfunctions.invokercho tài khoản dịch vụ theo tiện ích bổ sung. Xem phần Uỷ quyền truy cập bằng IAM. - Cập nhật mã xác minh mã thông báo để sử dụng email tài khoản dịch vụ bổ trợ Google Workspace nhằm xác minh chữ ký của mã thông báo Bearer. Xem phần Xác thực yêu cầu của Google.