您可以使用许可名单来指定已预先批准以供您的脚本或插件访问的特定网址。许可名单有助于保护用户数据;当您定义许可名单后,脚本项目将无法访问未列入许可名单的网址。
在安装测试部署时,此字段是可选的;但在创建版本控制的部署时,此字段是必填字段。
当您的脚本或插件执行以下操作时,可以使用许可名单:
- 使用 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/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
(通配符必须用作前导前缀)