Apps 脚本项目使用清单文件配置有关脚本及其操作的某些详细信息。如需了解如何查看和修改清单，请参阅清单。
本文档详细介绍了如何为 Google Workspace 插件配置清单。
Google Workspace 插件的清单结构
Google Workspace 插件使用 Apps 脚本项目清单文件从多个方面定义插件的外观和行为。Google Workspace 插件的清单属性整理在清单对象结构的 addOns 部分下。
Google Workspace 插件清单配置示例
以下清单示例显示了清单文件中用于定义 Google Workspace 插件的部分，其中包括以下几个方面：
- 清单的
addOns.common部分定义了该插件的名称、徽标网址、颜色以及其他与主机无关的常规设置。 - 该清单定义了通用首页，但也定义了日历、云端硬盘、文档、表格和幻灯片专用的首页。Gmail 使用默认首页。
- 示例清单设置可实现以下功能：
- 日历
eventOpen和eventUpdated触发器，以及两个 Google 日历会议解决方案。 - 两种通用操作。
- 云端硬盘
onItemsSelectedTrigger。 - Gmail 撰写操作和上下文触发器。
- Google 文档
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（通配符必须用作前导前缀）