将 API 阶段连接到 REST API 的自定义域名的路由规则 - Amazon API Gateway
API Gateway 路由规则条件类型限制

将 API 阶段连接到 REST API 的自定义域名的路由规则

路由规则是一组条件，匹配时会调用操作。例如，规则可以将任何传入的请求路由到自定义域名，该域名包含标头 Hello:World 并包含指向 REST API 的 production 阶段的基本路径 users。

规则按优先级顺序进行评估，如果您将路由模式设置为 ROUTING_RULE_THEN_API_MAPPING，则 API Gateway 将始终在评估任何 API 映射之前评估所有路由规则。以下列表描述了路由规则如何使用条件、操作和优先级。

条件

当规则的条件满足时，将执行其操作。API Gateway 最多支持两个标头条件和一个路径条件。API Gateway 会一起评估标头条件和基本路径条件。

您可以创建不带任何条件的规则。当 API Gateway 评估此规则时，将始终执行该操作。您可以创建不带任何条件的规则作为“捕获全部”规则。

有关标头条件的更多信息，请参阅匹配标头条件。有关路径条件的更多信息，请参阅匹配基本路径条件。

操作

操作是将条件与路由规则匹配的结果。当前，唯一受支持的操作是调用 REST API 的阶段。

每条规则可以有一个操作。

优先级

优先级决定了评估规则的顺序（从最低值到最高值）。规则不能具有相同的优先级。

您可以将优先级设置为 1-1000000。如果规则的优先级为 1，则 API Gateway 首先对其进行评估。我们建议在创建规则时，在优先级间添加间隔。这有助于您切换规则的优先级并添加新规则。有关更多信息，请参阅 更改路由规则的优先级。

有关 API Gateway 如何评估路由规则的示例，请参阅有关 API Gateway 如何评估路由规则的示例。

API Gateway 路由规则条件类型

下一节介绍路由规则条件类型。仅当所有条件均为 true 时，API Gateway 才会匹配规则。

匹配标头条件

创建标头条件时，可以匹配标头名称和标头 glob 值，例如 Hello:World。API Gateway 使用文字匹配来验证匹配标头条件。您的条件最多可以使用两个标头，并在标头之间使用 AND。例如，如果传入的请求包含 Hello:World 和 x-version:beta，则条件可以匹配。

标头名称匹配不区分大小写，但标头 glob 值区分大小写。Hello:World 将匹配 hello:World，但不匹配 Hello:world。

有关受限标头值的列表，请参阅限制。

将通配符与标头条件结合使用

只能在标头 glob 值中使用通配符，并且通配符必须是 *prefix-match、suffix-match* 或 *contains*。下表显示了如何使用通配符来匹配标头条件的示例。

标头条件 与路由规则匹配的请求 与路由规则不匹配的请求

x-version: a*

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: beta

  • x-version: users

x-version: *a

  • x-version: alpha

  • x-version: beta

  • x-version: account

  • x-version: backup

  • x-version: users

x-version: *a*

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: beta

  • x-version: users

x-version: *a* 和 x-version: *b*

  • x-version: backup

  • x-version: beta

  • x-version: account

  • x-version: alpha

  • x-version: users

x-version: b* 和 x-version: *a

  • x-version: beta

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: users

x-version: *

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: beta

  • x-version: users

无

如果您为多个标头值创建条件（例如 Accept:application/json,text/xml），我们建议您将 *contains* 用于标头条件，并避免使用逗号 (,) 字符创建条件。

由于 API Gateway 按字面匹配标头条件，因此可能会以不同的方式路由语义匹配。下表显示了路由规则结果的差异。

标头条件 与路由规则匹配的请求 与路由规则不匹配的请求

Accept: *json

  • Accept:application/json Accept:text/xml

  • Accept:application/json,text/xml

Accept: *json*

  • Accept:application/json Accept:text/xml

  • Accept:application/json,text/xml

无

匹配基本路径条件

创建基本路径条件时，如果传入的请求包含您指定的路径，则匹配该规则。匹配区分大小写，因此路径 New/Users 将与 new/users 不匹配。

您只能为一条基本路径创建基本路径条件。

有关受限基本路径条件的列表，请参阅限制。

使用基本路径条件删除基本路径

创建基本路径条件时，可以选择剥离基本路径。当您删除基本路径时，API Gateway 会在调用目标 API 时移除传入的匹配基本路径。这与您使用 API 映射时的行为相同。当您不删除基本路径时，API Gateway 会将整个基本路径转发到目标 API。我们建议您仅在重新创建 API 映射时才删除基本路径。

下表显示了 API Gateway 如何评估删除基本路径条件的示例。

状况 删除基本路径 传入请求 结果

如果基本路径包含 PetStoreShopper/dogs

 True

GET https://example.com/PetStoreShopper/dogs

API Gateway 调用 / 资源的 GET 方法。

如果基本路径包含 PetStoreShopper/dogs。

 False

GET https://example.com/PetStoreShopper/dogs

API Gateway 调用 PetStoreShopper/dogs 资源的 GET 方法。

如果基本路径包含 PetStoreShopper

 True

GET https://example.com/PetStoreShopper/dogs

API Gateway 调用 dogs 资源的 GET 方法。

如果基本路径包含 PetStoreShopper

 False

GET https://example.com/PetStoreShopper/dogs

API Gateway 调用 PetStoreShopper/dogs 资源的 GET 方法。

如果基本路径包含 PetStoreShopper

 True

GET https://example.com/PetStoreShopper?birds=available

API Gateway 使用查询字符串参数 birds=available 调用 / 资源的 GET 方法。

如果基本路径包含 PetStoreShopper

 False

GET https://example.com/PetStoreShopper?birds=available

API Gateway 使用查询字符串参数 birds=available 调用 /PetStoreShopper 资源的 GET 方法。

限制

  • 目标 API 和自定义域名必须位于同一个 AWS 账户中。

  • 每条规则可以有一个目标 API。

  • 您只能为私有自定义域名创建指向私有 API 的路由规则，以及为公有自定义域名创建指向公有 API 的路由规则。您不能混合公有资源和私有资源。

  • 如果自定义域名具有到 REST 和 HTTP API 的 API 映射，则不支持路由规则。

  • 最大优先级数字为 1000000。

  • 标头限制：

    • 每个 anyOf 条件只能包含一个标头值。

    • RFC 7230 规定了标头名称和标头 glob 值支持的仅有字符，即 a-z、A-Z、0-9 和以下特殊字符：*?-!#$%&'.^_`|~。

    • 可以在标头 glob 值中使用通配符，但通配符必须为 *prefix-match、suffix-match* 或 *contains*。不能在标头 glob 值的中间使用 *。

    • 不支持通配符标头名称。

    • 标头名称必须少于 40 个字符。

    • 标头 glob 值必须少于 128 个字符。

    • 中缀匹配的标头 glob 值必须少于 40 个字符。

    • 不支持将以下标头作为条件：

      • access-control-*

      • apigw-*

      • Authorization

      • Connection

      • Content-Encoding

      • Content-Length

      • Content-Location

      • Forwarded

      • Keep-Alive

      • Origin

      • Proxy-Authenticate

      • Proxy-Authorization

      • TE

      • Trailers

      • Transfer-Encoding

      • Upgrade

      • x-amz-*

      • x-amzn-*

      • x-apigw-api-id

      • X-Forwarded-For

      • X-Forwarded-Host

      • X-Forwarded-Proto

      • x-restAPI

      • Via

  • 基本路径限制：

    • 基本名称长度必须少于 128 个字符。

    • 基本路径必须仅包含字母、数字和以下字符：$-_.+!*'()/。

      正则表达式不支持这些字符。

    • 基本路径不能以反斜杠 (\) 字符开头或结尾。