插件使用清单文件 以配置有关应用及其操作的特定详细信息。
本文档详细介绍了如何为 Google Workspace 插件。
Google Workspace 插件的清单结构
Google Workspace 插件使用清单文件来定义 插件 外观和行为。
Google Workspace 插件的清单属性包括
整理到清单对象结构的 addOns
部分下。
- 有关 Apps 脚本清单文件的信息,请参阅 清单结构。
- 有关使用
HTTP 端点,请参阅 REST 资源:
projects.deployments
Google Workspace 插件清单配置示例
以下清单文件示例展示了清单文件中定义 Google Workspace 插件,包括以下几个方面:
addOns.common
部分定义了名称、徽标网址、颜色 独立于主机的常规设置- 该清单定义了一个通用首页,还定义了 Google 日历、云端硬盘、文档、 Google 表格及 Google 幻灯片专用的首页。 Gmail 使用默认主页。
- 示例清单设置支持以下各项:
<ph type="x-smartling-placeholder">
- </ph>
- 日历
eventOpen
和eventUpdated
触发器。 - (仅限 Apps 脚本)两个日历 会议解决方案。
- 两项通用操作。
- 云端硬盘
onItemsSelectedTrigger
。 - Gmail 撰写操作和上下文触发器。
- 一个文档
linkPreviewTriggers
对象。如需了解此触发器 请参阅预览包含智能条状标签的链接。 - 一个文档
createActionTriggers
对象。如需了解此触发器 请参阅通过“@”菜单创建第三方资源。 - Google 文档、表格 和幻灯片。
- 日历
oauthScopes
字段 设置项目的授权范围(对于 插件)。- (仅限 Apps 脚本)
urlFetchWhitelist
字段是一个字段,用于确保任何提取的端点都与指定的 HTTPS 网址前缀列表。如需了解详情,请参阅 将网址列入许可名单。
示例中的链接指向说明 该字段对应的 Apps 脚本的清单参考文档 和 HTTP Google Workspace 插件。
Apps 脚本
{ "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://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" }, "linkPreviewTriggers": [ { "runFunction": "onLinkPreview", "patterns": [ { "hostPattern": "example.com", "pathPrefix": "example-path" } ], "labelText": "Link preview", "localizedLabelText": { "es": "Link preview localized in Spanish" }, "logoUrl": "https://www.example.com/images/smart-chip-icon.png" } ], "createActionTriggers": [ { "id": "exampleId", "labelText": "Example label text", "localizedLabelText": { "es": "Label text localized in Spanish" }, "runFunction": "exampleFunction", "logoUrl": "https://www.example.com/images/case.png" } ] }, "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", "https://www.googleapis.com/auth/workspace.linkpreview" ], "urlFetchWhitelist": [ "https://www.example.com/myendpoint/" ] }
HTTP
{ "addOns": { "calendar": { "currentEventAccess": "READ_WRITE", "eventOpenTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen" }, "eventUpdateTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate" }, "eventAttachmentTrigger": { "label": "My Event Attachment", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment" }, "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen", "enabled": true } }, "common": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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://www.example.com/" ], "universalActions": [{ "label": "Open settings", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard" }, { "label": "Open Help URL", "openLink": "https://www.example.com/help" }], "useLocaleFromApp": true }, "drive": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen", "enabled": true }, "onItemsSelectedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected" } }, "gmail": { "composeTrigger": { "actions": [ { "label": "Add images to email", "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards" } ], "draftAccess": "METADATA" }, "contextualTriggers": [ { "unconditional": {}, "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen" } ] }, "docs": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" }, "linkPreviewTriggers": [ { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onLinkPreview", "patterns": [ { "hostPattern": "example.com", "pathPrefix": "example-path" } ], "labelText": "Link preview", "localizedLabelText": { "es": "Link preview localized in Spanish" }, "logoUrl": "https://www.example.com/images/smart-chip-icon.png" } ], "createActionTriggers": [ { "id": "exampleId", "labelText": "Example label text", "localizedLabelText": { "es": "Label text localized in Spanish" }, "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction", "logoUrl": "https://www.example.com/images/case.png" } ] }, "sheets": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors" } }, "slides": { "homepageTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "https://myownpersonaldomain.com/mypage?trigger=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", "https://www.googleapis.com/auth/workspace.linkpreview" ] }
将网址列入许可名单
8еа39680ц8 5138ц2ц823 800е90953а 1685бдфб67 8еа39680ц8 5138ц2ц823 800е90953а 1685бдфб67您可以使用许可名单来指定预先获准访问的特定网址 由脚本或插件触发许可名单有助于保护用户 data;指定许可名单后,脚本项目将无法访问 未列入许可名单。
安装测试部署时,此字段为可选项,但在使用 您需要创建版本化部署
当您的脚本或插件执行时,您可以使用许可名单 执行以下操作:
- 从外部位置(例如 HTTPS)检索或提取信息
端点)(使用 Apps 脚本
UrlFetch
) 服务。如需将用于提取的网址列入许可名单,请在清单文件中添加urlFetchWhitelist
字段。 - 在用户操作时打开或显示网址(对于
Google Workspace 插件会打开或显示
Google)。如需将网址列入许可名单以供打开,请在
addOns.common.openLinkUrlPrefixes
清单文件
将前缀添加到许可名单
如果您在清单文件中指定许可名单(通过将
addOns.common.openLinkUrlPrefixes
或 urlFetchWhitelist
字段),则必须
添加网址前缀列表。您添加到清单中的前缀必须
满足以下要求:
- 每个前缀都必须是有效网址。
- 每个前缀都必须使用
https://
(而不是http://
)。 - 每个前缀都必须包含完整的域名。
- 每个前缀都必须具有非空路径。例如:
https://www.google.com/
有效,但https://www.google.com
无效。 - 您可以使用通配符来匹配网址子网域前缀。
- 单个
*
通配符可用于addOns.common.openLinkUrlPrefixes
字段匹配所有链接,但不建议这样做,因为 用户的数据面临风险,并可能延长 附加审核流程。仅限 如果您的插件功能需要,请使用通配符。
在确定网址是否与许可名单中的前缀匹配时,以下规则 应用:
- 路径匹配区分大小写。
- 如果前缀与网址相同,则表示匹配。
- 如果网址相同或是该前缀的子网址,则匹配。
例如,前缀 https://example.com/foo
与以下网址匹配:
https://example.com/foo
https://example.com/foo/
https://example.com/foo/bar
https://example.com/foo?bar
https://example.com/foo#bar
使用通配符
您可以使用单个通配符 (*
) 来同时匹配
urlFetchWhitelist
和addOns.common.openLinkUrlPrefixes
字段。您不能使用多个通配符来匹配多个子网域,并且
通配符必须代表网址的前导前缀。
例如,前缀 https://*.example.com/foo
与以下内容匹配:
网址:
https://subdomain.example.com/foo
https://any.number.of.subdomains.example.com/foo
前缀 https://*.example.com/foo
与以下内容不匹配
网址:
https://subdomain.example.com/bar
(后缀不匹配)https://example.com/foo
(必须至少包含一个子域名)
当您尝试保存清单时,系统会强制执行一些前缀规则。对于 例如,如果您的 清单:
https://*.*.example.com/foo
(禁止使用多个通配符)https://subdomain.*.example.com/foo
(通配符必须用作前导前缀)