Apps 脚本项目使用清单文件来配置有关脚本及其操作的某些详细信息。如需了解如何查看和修改清单，请参阅清单。
本文档详细介绍了如何为 Google Workspace 插件配置清单。
Google Workspace 插件的清单结构
Google Workspace 插件使用 Apps 脚本项目清单文件定义插件外观和行为的多个方面。Google Workspace 插件的清单属性在清单对象结构的 addOns 部分进行整理。
Google Workspace 插件清单配置示例
以下清单示例显示了定义 Google Workspace 插件的清单文件部分，包括以下方面：
- 清单的
addOns.common部分定义了插件的名称、徽标网址、颜色和其他独立于主机的常规设置。 - 该清单定义了一个通用首页，但也定义了 Google 日历、云端硬盘、文档、表格和幻灯片的首页。Gmail 使用默认首页。
- 清单设置示例会启用以下功能：
- 日历
eventOpen和eventUpdated触发器，以及两个 Google 日历会议解决方案。 - 两种通用操作。
- 一个云端硬盘
onItemsSelectedTrigger。 - Gmail 撰写操作和内容相关触发器。
- 文档
linkPreviewTrigger。如需了解此触发器，请参阅预览智能条状标签的链接。 - Google 文档、表格和幻灯片的文件专属界面。
- 日历
oauthScopes字段用于设置项目的授权范围（插件通常要求提供）。urlFetchWhitelist字段是一个字段，用于确保所有提取的端点与指定的 HTTPS 网址前缀列表匹配。此字段对于测试部署是可选的，但对于部署来说是必填字段。如需了解详情，请参阅许可名单网址。
示例中的链接指向清单参考文档中相应字段的说明。
// 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"
},
"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"
}
]
},
"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/"
],
}
许可名单网址
您可以使用许可名单指定已预先获准通过脚本或插件访问的特定网址。许可名单有助于保护用户数据；在您定义许可名单后，脚本项目将无法访问尚未列入许可名单的网址。
当脚本或插件执行以下操作时，您可以使用许可名单：
- 使用 Apps 脚本
UrlFetch服务从外部位置（例如 HTTPS 端点）检索或提取信息。要将网址列入抓取许可名单，请在清单文件中添加urlFetchWhitelist字段。 - 打开或显示网址以响应用户操作（对于打开或显示 Google 外部网址的 Google Workspace 插件而言，是必需的）。如需将网址列入开放许可名单，请在清单文件中添加
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/foohttps://example.com/foo/https://example.com/foo/barhttps://example.com/foo?barhttps://example.com/foo#bar
使用通配符
您可以使用单个通配符 (*) 来匹配 urlFetchWhitelist 和 addOns.common.openLinkUrlPrefixes 字段的子网域。您不能使用多个通配符来匹配多个子网域，并且通配符必须代表网址的开头前缀。
例如，前缀 https://*.example.com/foo 与以下网址匹配：
https://subdomain.example.com/foohttps://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（通配符必须用作前导前缀）