许可名单网址

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

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

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

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