本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 將 API 階段連線至 REST API 自訂網域名稱的路由規則
<a name="rest-api-routing-rules"></a>

路由規則是一組條件，若符合條件，則會調用動作。例如，規則可以將包含 `Hello:World` 標頭且包含基本路徑 `users` 之自訂網域名稱的任何傳入請求，路由傳送至 REST API 的 `production` 階段。

規則會依優先順序加以評估，若您將路由模式設定為 `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 的階段。  
每一項規則可以有一個動作。

**Priority**  
優先順序決定評估規則的順序，從最低值到最高值。規則不可具有相同的優先順序。  
您可以設定的優先順序範圍為 1 到 1,000,000。如果規則的優先順序為 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>

下節說明路由規則條件類型。API Gateway 只有在所有條件都為 true 時才符合規則。

### 比對標頭條件
<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_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `x-version: *`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
|  `Accept: *json*`  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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 映射，則不支援路由規則。
+ 最大優先順序數字為 1,000,000。
+ 標頭限制：
  + 每一項 `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 個字元。
  + infix 比對的標頭 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 個字元。
  + 基本路徑只能包含字母、數字和下列字元：`$-_.+!*'()/`。

    規則表達式 (regex) 不支援這些字元。
  + 基本路徑的開頭或結尾不可為反斜線 (`\`)。