使用 API 映射將 API 階段連線至 REST API 的自訂網域名稱 - Amazon API Gateway
對自訂網域名稱的傳入請求對應 API 請求限制建立 API 映射

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

使用 API 映射將 API 階段連線至 REST API 的自訂網域名稱

您可以使用 API 映射將 API 階段連線至自訂網域名稱。這會透過您的自訂網域名稱將流量傳送至 API。

API 映射指定一個 API，一個階段，以及選擇性用於映射的路徑。例如，您可以將 https://api.example.com/orders 對應至 API 的 production 階段。

您可以將 HTTP 和 REST API 階段映射至相同的自訂網域名稱。

建立 API 映射之前，您必須先擁有 API、階段和自訂網域名稱。如需進一步了解如何建立自訂網域名稱，請參閱在 API Gateway 中設定區域性自訂網域名稱。

對自訂網域名稱的傳入請求

當您將自訂網域名稱對應至 API 的階段時，API Gateway 會去除傳入的基本路徑。這樣會從 API 的調用中移除對應的基本路徑。例如，如果您的基本路徑映射是 https://api.example.com/orders/shop/5 至 test 階段，而您使用下列請求 https://api.example.com/orders/shop/5/hats，則 API Gateway 會調用 API test 階段的 /hats 資源，而非 orders/shop/5/hats 資源。

對應 API 請求

以下說明 API Gateway 如何評估 API 映射。

您可以使用單一層級映射來建立 API 映射，例如從 orders 至 API beta 階段的 API 映射，以及從 shipping 至 API alpha 階段的 API 映射。對於具有 TLS 1.2 安全政策的區域自訂網域名稱，API Gateway 可支援多層 API 映射。您可以建立從 orders/v1/items 至 API alpha 階段及 orders/v2/items 至 API beta 階段的 API 映射。當您建立有多個層級的映射時，API Gateway 會將請求傳送至具有最長相符路徑的 API 映射。

您可以建立對空白路徑 (none) 的 API 映射。如果沒有路徑與請求相符，則 API Gateway 會將請求傳送到空白路徑 (none)。

在此範例中，自訂網域名稱 https://api.example.com 具有下列 API 映射。

API 映射 選取的 API

(none)

API 1

orders

API 2

orders/v1/items

API 3

orders/v2/items

API 4

orders/v1/items/categories

API 5

下表顯示 API Gateway 如何將上述 API 映射套用至範例請求。

要求 選取的 API 說明

https://api.example.com/orders

API 2

請求完全符合此 API 映射。

https://api.example.com/orders/v1/items

API 3

請求完全符合此 API 映射。

https://api.example.com/orders/v2/items

API 4

請求完全符合此 API 映射。

https://api.example.com/orders/v1/items/123

API 3

API Gateway 會選擇具有最長相符路徑的映射。請求結束時的 123 不會影響選擇。請參閱 對自訂網域名稱的傳入請求。

https://api.example.com/orders/v2/items/categories/5

API 5

API Gateway 會選擇具有最長相符路徑的映射。

https://api.example.com/customers

API 1

API Gateway 使用空白映射作為全部擷取。

https://api.example.com/ordersandmore

API 2

API Gateway 會選擇具有最長相符字首的映射。

針對設定使用單一層級映射的自訂網域名稱，例如只有 https://api.example.com/orders 和 https://api.example.com/，API Gateway 會選擇 API 1，因為沒有與 ordersandmore 相符的路徑。

限制

  • 在 API 映射中，自訂網域名稱和映射APIs 必須在相同的 AWS 帳戶中。

  • API 映射只能包含字母、數字和下列字元：$-_.+!*'()/。

  • API 映射中路徑的最大長度為 300 個字元。

  • 您可以為每個域名設定具有 200 個具多個層級的 API 映射。此限制不包括具有單一層級的 API 映射，例如 /prod。

  • 您只能將 HTTP API 映射至具有 TLS 1.2 安全政策的區域自訂網域名稱。

  • 您無法將 WebSocket API 映射至與 HTTP API 或 REST API 相同的自訂網域名稱。

  • 建立您的 API 映射後，您必須建立或更新 DNS 提供者的資源記錄，以映射至您的 API 端點。

  • 如果您建立具有多層的 API 映射，API Gateway 會將所有標頭名稱轉換為小寫。

建立 API 映射

若要建立 API 映射，您必須先建立自訂網域名稱、API 和階段。您自訂網域名稱的路由模式必須設定為 ROUTING_RULE_THEN_API_MAPPING 或 API_MAPPING_ONLY。如需如何設定路由模式的相關資訊，請參閱 為您的自訂網域名稱設定路由模式。

如需建立所有資源的範例 AWS Serverless Application Model 範本，請參閱 GitHub 上具有 SAM 的工作階段。

AWS Management Console

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  2. 從主要導覽窗格中，選擇 Custom Domain Names (自訂網域名稱)。

  3. 選擇自訂網域名稱。

  4. 在路由詳細資訊索引標籤上，選擇設定 API 映射。

  5. 輸入映射的 API、階段及路徑。

  6. 選擇儲存。

AWS CLI

以下 create-api-mapping 命令會建立 API 映射。在此範例中，API Gateway 會將請求傳送至 api.example.com/v1/orders，到指定的 API 和階段。

注意

若要建立具有多個層級的 API 映射，您必須使用 apigatewayv2。

aws apigatewayv2 create-api-mapping \
    --domain-name api.example.com \
    --api-mapping-key v1/orders \
    --api-id a1b2c3d4 \
    --stage test
AWS CloudFormation

下列 AWS CloudFormation 範例會建立 API 映射。

注意

若要建立具有多個層級的 API 映射，您必須使用 AWS::ApiGatewayV2。

MyApiMapping:
  Type: 'AWS::ApiGatewayV2::ApiMapping'
  Properties:
    DomainName: api.example.com
    ApiMappingKey: 'orders/v2/items'
    ApiId: !Ref MyApi
    Stage: !Ref MyStage