將 API 階段連線至 REST API 自訂網域名稱的路由規則 - Amazon API Gateway
API Gateway 路由規則條件類型限制

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

將 API 階段連線至 REST API 自訂網域名稱的路由規則

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

規則會依優先順序加以評估，若您將路由模式設定為 ROUTING_RULE_THEN_API_MAPPING，則 API Gateway 一律會先評估所有路由規則，再評估任何 API 映射。下列清單說明路由規則如何使用條件、動作和優先順序。

條件

滿足規則的條件時，即會執行它的動作。API Gateway 最多可支援兩個標頭條件和一個路徑條件。API Gateway 會一起評估標頭條件和基本路徑條件。

您可以建立規則，而不設任何條件。當 API Gateway 評估此規則時，一律會執行動作。您可以建立規則，而不設任何條件，以作為全部擷取規則。

如需標頭條件的詳細資訊，請參閱 比對標頭條件。如需路徑條件的詳細資訊，請參閱 比對基本路徑條件。

動作

動作是符合路由規則條件的結果。目前，唯一支援的動作是調用 REST API 的階段。

每一項規則可以有一個動作。

優先順序

優先順序決定評估規則的順序，從最低值到最高值。規則不可具有相同的優先順序。

您可以設定的優先順序範圍為 1 到 1,000,000。如果規則的優先順序為 1，則 API Gateway 會先評估此規則。我們建議您在建立規則時，於優先順序之間插入間隙。這樣做有助於切換規則的優先順序，並新增新規則。如需詳細資訊，請參閱變更路由規則的優先順序。

如需 API Gateway 如何評估路由規則的範例，請參閱 API Gateway 如何評估路由規則的範例。

API Gateway 路由規則條件類型

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

比對標頭條件

建立標頭條件時，您可以比對標頭名稱和標頭 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 映射，則不支援路由規則。

  • 最大優先順序數字為 1,000,000。

  • 標頭限制：

    • 每一項 anyOf 條件只能包含一個標頭值。

    • RFC 7230 會指定下列唯一允許的標頭名稱和標頭 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) 不支援這些字元。

    • 基本路徑的開頭或結尾不可為反斜線 (\)。