Apps 脚本项目使用清单文件来配置脚本及其操作的特定详细信息。如需了解如何查看和修改清单，请参阅清单。
本文档详细介绍了为 Google Workspace 插件配置清单。
Google Workspace 插件的清单结构
Google Workspace 插件使用 Apps 脚本项目清单文件定义插件的外观和行为的多个方面。Google Workspace 插件的清单属性在清单对象结构的 addOns 部分下整理。
Google Workspace 插件清单配置示例
以下清单示例显示了定义 Google Workspace 插件的清单文件部分，包括以下方面：
- 清单的
addOns.common部分定义了插件的名称、徽标网址、颜色以及其他与主机无关的常规设置。 - 该清单定义了一个通用首页，还定义了特定于 Google 日历、云端硬盘、文档、表格和幻灯片的首页。Gmail 使用默认首页。
- 示例清单设置可启用以下功能：
- 日历
eventOpen和eventUpdated触发器以及两个日历会议解决方案。 - 两个通用操作。
- 云端硬盘
onItemsSelectedTrigger。 - Gmail 撰写操作和上下文触发器。
- 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"
}
},
"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/"
],
}
许可名单网址
有时，您可能希望脚本或插件打开网址来响应用户操作。有时，您可能希望脚本或插件使用 Apps 脚本 UrlFetch 服务从外部位置检索信息。在这两种情况下，您都必须将您在项目清单中打开或提取的网址列入许可名单。
列入许可名单是指定脚本或插件预先批准访问特定网址的过程。此要求有助于保护用户数据；如果您定义了许可名单，脚本项目无法访问尚未列入许可名单的网址。 Google Workspace 插件要求先将网址列入许可名单，然后才能提取或打开这些网址。
您可以将网址列入提取许可名单，方法是将相应网址或匹配的前缀添加到 urlFetchWhitelist 清单字段。对于 Google Workspace插件项目，您可以将要打开的网址或匹配的前缀添加到 addOns.common.openLinkUrlPrefixes 清单字段，从而列入许可名单。
您添加到清单中的前缀必须符合以下要求：
- 每个前缀都必须是有效网址。
- 每个前缀都必须使用
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（通配符必须用作前置前缀）