# 将 API 阶段连接到 REST API 的自定义域名的路由规则
<a name="rest-api-routing-rules"></a>

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

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

**条件**  
当规则的条件满足时，将执行其操作。API Gateway 最多支持两个标头条件和一个路径条件。API Gateway 会一起评估标头条件和基本路径条件。  
您可以创建不带任何条件的规则。当 API Gateway 评估此规则时，将始终执行该操作。您可以创建不带任何条件的规则作为“捕获全部”规则。  
有关标头条件的更多信息，请参阅[匹配标头条件](#rest-api-routing-rules-condition-headers)。有关路径条件的更多信息，请参阅[匹配基本路径条件](#rest-api-routing-rules-condition-path)。

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

**优先级**  
优先级决定了评估规则的顺序（从最低值到最高值）。规则不能具有相同的优先级。  
您可以将优先级设置为 1-1000000。如果规则的优先级为 1，则 API Gateway 首先对其进行评估。我们建议在创建规则时，在优先级间添加间隔。这有助于您切换规则的优先级并添加新规则。有关更多信息，请参阅 [更改路由规则的优先级](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority)。

有关 API Gateway 如何评估路由规则的示例，请参阅[有关 API Gateway 如何评估路由规则的示例](rest-api-routing-rules-examples.md)。

## API Gateway 路由规则条件类型
<a name="rest-api-routing-rules-condition-types"></a>

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

### 匹配标头条件
<a name="rest-api-routing-rules-condition-headers"></a>

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

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

有关受限标头值的列表，请参阅[限制](#rest-api-routing-rules-restrictions)。

#### 将通配符与标头条件结合使用
<a name="rest-api-routing-rules-condition-headers-wildcards"></a>

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


|  标头条件  |  与路由规则匹配的请求  |  与路由规则不匹配的请求  | 
| --- | --- | --- | 
|  `x-version: a*`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `x-version: *a`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `x-version: *a*`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `x-version: *a*` 和 `x-version: *b*`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `x-version: b*` 和 `x-version: *a`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `x-version: *`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  无  | 

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

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


|  标头条件  |  与路由规则匹配的请求  |  与路由规则不匹配的请求  | 
| --- | --- | --- | 
|  `Accept: *json`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `Accept: *json*`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  无  | 

### 匹配基本路径条件
<a name="rest-api-routing-rules-condition-path"></a>

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

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

有关受限基本路径条件的列表，请参阅[限制](#rest-api-routing-rules-restrictions)。

#### 使用基本路径条件删除基本路径
<a name="rest-api-routing-rules-condition-path-split"></a>

创建基本路径条件时，可以选择剥离基本路径。当您删除基本路径时，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` 方法。  | 

## 限制
<a name="rest-api-routing-rules-restrictions"></a>
+ 目标 API 和自定义域名必须位于同一个 AWS 账户中。
+ 每条规则可以有一个目标 API。
+ 您只能为私有自定义域名创建指向私有 API 的路由规则，以及为公有自定义域名创建指向公有 API 的路由规则。您不能混合公有资源和私有资源。
+ 如果自定义域名具有到 REST 和 HTTP API 的 API 映射，则不支持路由规则。
+ 最大优先级数字为 1000000。
+ 标头限制：
  + 每个 `anyOf` 条件只能包含一个标头值。
  + [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230) 规定了标头名称和标头 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 个字符。
  + 基本路径必须仅包含字母、数字和以下字符：`$-_.+!*'()/`。

    正则表达式不支持这些字符。
  + 基本路径不能以反斜杠 (`\`) 字符开头或结尾。