UrlPrefix 字符串

项目
03/13/2025

在 HTTP 服务器 API 中，UrlPrefix 是一个宽字符（UTF-16） Unicode 字符串，其规范形式指定 URL 命名空间的节。它用于保留用户帐户的 URL 命名空间部分，或为进程注册 URL 命名空间的一部分。

UrlPrefix 格式

UrlPrefix 具有以下语法：

“scheme：//host：port/relativeURI”

UrlPrefix 的方案、主机和端口元素必须存在且非空，并且必须遵循以下规则：

方案

必须是 http 或 https，全部采用小写形式。

主机

必须是完全限定的域名、IPv4 或 IPv6 文本字符串或通配符。与必须小写的方案不同，主机部分不区分大小写。根据主机部分的指定方式，UrlPrefix 属于以下四个路由类别之一，下面更详细地介绍了这些类别：

强通配符

明确

IP 绑定弱通配符

弱通配符

端口

不以零开头且表示有效 TCP 端口号（1 到 65,535）的十进制数字字符串。此值不能为通配符。

relativeURI

relativeURI 元素是可选的，但如果存在，必须始终后跟斜杠字符（“/）。这是一个前缀字符串，指示相对于方案、主机和端口值指定的计算机的命名空间中的子树。与必须小写的方案不同，relativeURI 部分不区分大小写。

正确格式的 UrlPrefixes 的示例包括：

https://www.adatum.com:80/vroot/
https://adatum.com:443/secure/database/
https://+:80/vroot/

Host-Specifier 类别

为了灵活性和易用性，HTTP 服务器 API 支持四种不同的方法来指定主机。以下四个主机说明符类别按优先级顺序列出：

强通配符（加号）

当 UrlPrefix 的主机元素由单一加号（+）组成时，UrlPrefix 在其方案、端口和 relativeURI 元素的上下文中匹配所有可能的主机名，并属于强通配符类别。

当应用程序需要处理一个或多个 relativeURIs 的请求时，无论这些请求到达计算机的方式或它们在主机标头中指定的站点如何，强通配符都很有用。在这种情况下，使用强通配符可避免指定主机和/或 IP 地址的详尽列表。

显式

显式主机名（例如主机元素中的完全限定域名）将 UrlPrefix 置于显式类别中。此类主机元素直接与传入请求的 Host 标头匹配。

显式主机规范对于多站点应用程序（如传送不同内容的 Web 服务器）非常有用，具体取决于请求定向到的站点。

IP 绑定弱通配符

当 IP 地址显示为主机元素时，UrlPrefix 将属于 IP 绑定的弱通配符类别。此类 UrlPrefix 与具有指定方案、端口和 relativeURI 的指定 IP 接口的任何主机名匹配，并且尚未通过强通配符或显式 UrlPrefix 进行匹配。 IP 地址采用主机元素中的两种形式之一：

IPv4 文本字符串: IPv4 文本由四个点点小数组成，每个数字介于 0-255 之间，例如 192.168.0.0。
IPv6 文本字符串: IPv6 文本字符串括在方括号中，并包含用冒号分隔的十六进制数字;例如：[：：1] 或 [3ffe：ffff：：6ECB：0101]。

IP 绑定弱通配符主机说明符适用于根据传入请求采用的路由改变其服务内容的应用程序。不要依赖于 IP 绑定弱通配符主机说明符来强制实施安全性。

弱通配符（星号）

当星号 \ 显示为主机元素时，UrlPrefix 将属于弱通配符类别。此类 UrlPrefix 匹配与指定的方案、端口和 relativeURI 关联的任何主机名，这些主机名尚未与强通配符、显式或 IP 绑定的弱通配符 UrlPrefix 匹配。

在某些情况下，可以将此主机规范用作默认的 catch-all，或者可用于指定大量 URL 命名空间，而无需使用许多 UrlPrefixes。

预留和注册期间的 UrlPrefix 冲突检测

出于预留和注册目的，UrlPrefix 的四种不同类别将单独处理，而无需相互引用。只要 UrlPrefixes 位于不同的类别中，就可以注册冲突的 UrlPrefixes。只有在同一类别内，冲突会导致预留尝试失败。

例如，可以保留显式 UrlPrefix https://www.adatum.com:80/vroot/ 和冲突的强通配符 UrlPrefix https://+:80/vroot/，因为它们属于不同的类别。但是，后续尝试将 https://+:80/vroot/ 保留给其他用户会失败，因为它会与其自己的类别中的现有预留发生冲突。

路由行为

路由传入 HTTP 请求时，HTTP 服务器 API 以强通配符类别开头，并将传入 URL 与该类别中的已注册和保留的 UrlPrefixes 进行比较。

如果传入 URL 与预留匹配，但不与注册匹配，则 HTTP 服务器 API 将失败请求。这可以防止较低优先级的注册能够选取不适合它的请求。失败时的状态为 400（“错误请求”）而不是 503（“服务不可用”），因为负载均衡网关有时会错误地解释为指示服务器已重载。

如果在类别中找到匹配的注册，则请求将路由到与该注册关联的请求队列。请求始终路由到与类别中最长匹配 UrlPrefix 关联的队列。

如果在类别中找不到匹配项，则 HTTP 服务器 API 将转到显式类别并重复相同的过程。概括而言，检查类别的顺序如下：

强通配符
明确
IP-Bound 弱通配符
弱通配符

如果未在任何类别中找到匹配项，则 HTTP 服务器 API 发送状态代码为 400 的响应，以指示无法路由请求。

最长匹配规则

在每个 UrlPrefix 类别中，HTTP 服务器 API 将请求路由到与最长匹配 UrlPrefix 关联的队列。例如，假设以下两个 UrlPrefixes 注册到不同的队列：

Queue1 https://www.adatum.com:80/
Queue2 https://www.adatum.com:80/dir/sna/

HTTP 服务器 API 将 https://www.adatum.com:80/default.htm 的请求路由到 Queue1，并将 https://www.adatum.com:80/dir/sna/snadefault.htm 的请求路由到 Queue2。它会将 https://www.adatum.com:80/dir/app.htm 请求路由到 Queue1，因为最长的完整匹配项与 https://www.adatum.com:80/ UrlPrefix（而不是 https://www.adatum.com:80/dir/sna UrlPrefix）匹配。

通过