许可名单网址

您可以使用许可名单来指定已预先批准可供脚本或插件访问的特定网址。许可名单有助于保护用户数据；定义许可名单后，脚本项目便无法访问未添加到许可名单中的网址。

安装测试部署时，此字段为可选字段；但创建版本化部署时，此字段为必填字段。

当脚本或插件执行以下操作时，您需要使用许可名单：

  • 使用 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 （通配符必须用作前导前缀）