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服务从外部位置（例如 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（通配符必须用作前导前缀）