Dự án Apps Script sử dụng tệp tệp kê khai để định cấu hình một số thông tin chi tiết nhất định về tập lệnh và hoạt động của tập lệnh đó. Để tìm hiểu cách xem và chỉnh sửa tệp kê khai, hãy xem phần Tệp kê khai.
Tài liệu này trình bày chi tiết về cách định cấu hình tệp kê khai cho Tiện ích bổ sung của Google Workspace.
Cấu trúc tệp kê khai cho Tiện ích bổ sung của Google Workspace
Tiện ích bổ sung của Google Workspace sử dụng tệp kê khai của dự án Apps Script
để xác định một số khía cạnh về giao diện và hành vi của tiện ích bổ sung.
Các thuộc tính tệp kê khai cho Tiện ích bổ sung của Google Workspace được sắp xếp trong
phần addOns
của cấu trúc đối tượng tệp kê khai.
Ví dụ về cấu hình tệp kê khai của tiện ích bổ sung trên Google Workspace
Mẫu tệp kê khai dưới đây cho thấy phần của tệp kê khai xác định Tiện ích bổ sung của Google Workspace, bao gồm những khía cạnh sau:
- Phần
addOns.common
của tệp kê khai xác định tên, URL biểu trưng, màu sắc và các chế độ cài đặt chung, độc lập khác với tiện ích bổ sung. - Tệp kê khai xác định trang chủ phổ biến, nhưng cũng xác định trang chủ dành riêng cho Lịch, Drive, Tài liệu, Trang tính và Trang trình bày. Gmail sử dụng trang chủ mặc định.
- Chế độ cài đặt tệp kê khai mẫu cho phép các chế độ sau:
- Lịch
eventOpen
vàeventUpdated
trình kích hoạt cùng với hai giải pháp hội nghị trên Lịch. - Hai thao tác chung.
onItemsSelectedTrigger
trên Drive.- Thao tác soạn Gmail và trình kích hoạt theo ngữ cảnh.
- Giao diện dành riêng cho tệp cho Tài liệu, Trang tính và Trang trình bày.
- Lịch
- Trường
oauthScopes
đặt phạm vi uỷ quyền cho dự án (thường bắt buộc đối với các tiện ích bổ sung). - Trường
urlFetchWhitelist
là trường không bắt buộc đảm bảo rằng mọi điểm cuối đã tìm nạp đều khớp với danh sách tiền tố URL HTTPS được chỉ định. Để biết thêm thông tin, hãy xem bài viết URL danh sách cho phép.
Các đường liên kết trong mẫu sẽ dẫn trực tiếp đến phần mô tả của trường đó trong tài liệu tham khảo về tệp kê khai.
// Sample configuration of the addOns section in a manifest file: { "addOns": { "calendar": { "createSettingsUrlFunction": "getConferenceSettingsPageUrl", "conferenceSolution": [{ "id": "my-video-conf", "logoUrl": "https://lh3.googleusercontent.com/...", "name": "My Video Conference", "onCreateFunction": "onCreateMyVideoConference" }, { "id": "my-streamed-conf", "logoUrl": "https://lh3.googleusercontent.com/...", "name": "My Streamed Conference", "onCreateFunction": "onCreateMyStreamedConference" }], "currentEventAccess": "READ_WRITE", "eventOpenTrigger": { "runFunction": "onCalendarEventOpen" }, "eventUpdateTrigger": { "runFunction": "onCalendarEventUpdate" }, "eventAttachmentTrigger": { "label": "My Event Attachment", "runFunction": "onCalendarEventAddAttachment" }, "homepageTrigger": { "runFunction": "onCalendarHomePageOpen", "enabled": true } }, "common": { "homepageTrigger": { "runFunction": "onDefaultHomePageOpen", "enabled": true }, "layoutProperties": { "primaryColor": "#ff392b", "secondaryColor": "#d68617" }, "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png", "name": "Demo Google Workspace Add-on", "openLinkUrlPrefixes": [ "https://mail.google.com/", "https://script.google.com/a/google.com/d/", "https://drive.google.com/a/google.com/file/d/", "https://en.wikipedia.org/wiki/", "https://www.example.com/" ], "universalActions": [{ "label": "Open settings", "runFunction": "getSettingsCard" }, { "label": "Open Help URL", "openLink": "https://www.example.com/help" }], "useLocaleFromApp": true }, "drive": { "homepageTrigger": { "runFunction": "onDriveHomePageOpen", "enabled": true }, "onItemsSelectedTrigger": { "runFunction": "onDriveItemsSelected" } }, "gmail": { "composeTrigger": { "selectActions": [ { "text": "Add images to email", "runFunction": "getInsertImageComposeCards" } ], "draftAccess": "METADATA" }, "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "onGmailMessageOpen" } ] }, "docs": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" } }, "sheets": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" } }, "slides": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedEditors" } }, "oauthScopes": [ "https://www.googleapis.com/auth/calendar.addons.execute", "https://www.googleapis.com/auth/calendar.addons.current.event.read", "https://www.googleapis.com/auth/calendar.addons.current.event.write", "https://www.googleapis.com/auth/drive.addons.metadata.readonly", "https://www.googleapis.com/auth/gmail.addons.current.action.compose", "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/script.external_request", "https://www.googleapis.com/auth/script.locale", "https://www.googleapis.com/auth/script.scriptapp", "https://www.googleapis.com/auth/drive.file", "https://www.googleapis.com/auth/documents.currentonly", "https://www.googleapis.com/auth/spreadsheets.currentonly", "https://www.googleapis.com/auth/presentations.currentonly" ], "urlFetchWhitelist": [ "https://www.example.com/myendpoint/" ], }
URL của danh sách cho phép
Bạn sử dụng danh sách cho phép để chỉ định các URL cụ thể đã được phê duyệt trước bằng tập lệnh hoặc tiện ích bổ sung của bạn. Danh sách cho phép giúp bảo vệ dữ liệu người dùng; khi bạn xác định một danh sách cho phép, các dự án tập lệnh không thể truy cập vào các URL không có trong danh sách cho phép.
Bạn sử dụng danh sách cho phép khi tập lệnh hoặc tiện ích bổ sung thực hiện các thao tác sau:
- Truy xuất hoặc tìm nạp thông tin từ một vị trí bên ngoài (chẳng hạn như các điểm cuối HTTPS) bằng cách sử dụng dịch vụ Apps Script
UrlFetch
. Để đưa các URL vào danh sách cho phép, hãy đưa trườngurlFetchWhitelist
vào tệp kê khai. - Mở hoặc hiển thị một URL để phản hồi hành động của người dùng (Bắt buộc đối với
các tiện ích bổ sung của Google Workspace mở hoặc hiển thị URL nằm ngoài
Google). Để đưa URL vào danh sách cho phép mở, hãy bao gồm trường
addOns.common.openLinkUrlPrefixes
trong tệp kê khai của bạn.
Thêm tiền tố vào danh sách cho phép
Khi chỉ định danh sách cho phép trong tệp kê khai (bằng cách thêm trường addOns.common.openLinkUrlPrefixes
hoặc urlFetchWhitelist
), bạn phải thêm danh sách tiền tố URL. Tiền tố mà bạn thêm vào tệp kê khai phải
đáp ứng các yêu cầu sau:
- Mỗi tiền tố phải là một URL hợp lệ.
- Mỗi tiền tố phải sử dụng
https://
, chứ không phảihttp://
. - Mỗi tiền tố phải có một miền đầy đủ.
- Mỗi tiền tố phải có một đường dẫn không trống. Ví dụ:
https://www.google.com/
hợp lệ nhưnghttps://www.google.com
thì không. - Bạn có thể sử dụng ký tự đại diện để khớp với các tiền tố miền con của URL.
- Bạn có thể dùng một ký tự đại diện
*
trong trườngaddOns.common.openLinkUrlPrefixes
để khớp với tất cả các đường liên kết, nhưng bạn không nên làm như vậy vì việc này có thể khiến dữ liệu của người dùng gặp rủi ro và có thể kéo dài quá trình xem xét bổ sung. Chỉ sử dụng ký tự đại diện nếu chức năng tiện ích bổ sung của bạn yêu cầu ký tự đại diện.
Khi xác định xem một URL có khớp với một tiền tố có trong danh sách cho phép hay không, các quy tắc sau sẽ áp dụng:
- Việc so khớp đường dẫn có phân biệt chữ hoa chữ thường.
- Nếu tiền tố giống hệt với URL thì đó là một kết quả phù hợp.
- Nếu URL giống nhau hoặc con của tiền tố, thì URL đó là một kết quả phù hợp.
Ví dụ: tiền tố https://example.com/foo
khớp với các URL sau:
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
Sử dụng ký tự đại diện
Bạn có thể sử dụng một ký tự đại diện duy nhất (*
) để so khớp một miền con cho cả trường urlFetchWhitelist
và addOns.common.openLinkUrlPrefixes
. Bạn không thể sử dụng nhiều ký tự đại diện để so khớp nhiều miền con và ký tự đại diện phải đại diện cho tiền tố hàng đầu của URL.
Ví dụ: tiền tố https://*.example.com/foo
khớp với các URL sau:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
Tiền tố https://*.example.com/foo
không khớp với các URL sau:
https://subdomain.example.com/bar
(hậu tố không khớp)https://example.com/foo
(phải có ít nhất một miền con)
Một số quy tắc về tiền tố được thực thi khi bạn cố gắng lưu tệp kê khai của mình. Ví dụ: các tiền tố sau đây sẽ gây ra lỗi nếu chúng xuất hiện trong tệp kê khai khi bạn cố gắng lưu:
https://*.*.example.com/foo
(nhiều ký tự đại diện bị cấm)https://subdomain.*.example.com/foo
(phải sử dụng ký tự đại diện làm tiền tố chính)