API Gateway 中 REST API 的參數映射範例 - Amazon API Gateway
範例 1：將方法請求參數對應至整合請求參數範例 2：將多個方法請求參數對應至不同的整合請求參數範例 3：將欄位從 JSON 請求內文對應至整合請求參數範例 4：將整合回應對應至方法回應

API Gateway 中 REST API 的參數映射範例

下列範例示範如何使用 API Gateway 主控台、OpenAPI 和 AWS CloudFormation 範本建立參數映射表達式。如需如何使用參數映射來建立所需 CORS 標頭的範例，請參閱 API Gateway 中 REST API 的 CORS。

範例 1：將方法請求參數對應至整合請求參數

下列範例會將方法請求標頭參數 puppies 對應至整合請求標頭參數 DogsAge0。

AWS Management Console
若要對應方法請求參數

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

  2. 選擇 REST API。

  3. 選擇一個方法。

    您的方法必須有非代理整合。

  4. 針對方法請求設定，選擇編輯。

  5. 選擇 HTTP 請求標頭。

  6. 選擇新增標頭。

  7. 對於名稱，輸入 puppies。

  8. 選擇儲存。

  9. 選擇整合請求索引標籤，然後針對整合請求設定，選擇編輯。

    AWS Management Console 會自動將參數映射從 method.request.header.puppies 新增至 puppies，但您需要變更名稱，使其符合整合端點預期的請求標頭參數。

  10. 對於名稱，輸入 DogsAge0。

  11. 選擇儲存。

  12. 重新部署 API 以使變更生效。

下列步驟說明如何驗證參數映射是否成功。

(選用) 測試參數映射

  1. 選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

  2. 針對標頭，輸入 puppies:true。

  3. 選擇測試。

  4. 在日誌中，結果應如下所示：

    Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations: 
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}

    請求標頭參數已從 puppies 變更為 DogsAge0。

AWS CloudFormation

在此範例中，您使用 body 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。

AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body:
        openapi: 3.0.1
        info:
          title: ParameterMappingExample
          version: "2025-02-04T00:30:41Z"
        paths:
          /pets:
            get:
              parameters:
                - name: puppies
                  in: header
                  schema:
                    type: string
              responses:
                "200":
                  description: 200 response
              x-amazon-apigateway-integration:
                httpMethod: GET
                uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
                responses:
                  default:
                    statusCode: "200"
                requestParameters:
                  integration.request.header.DogsAge0: method.request.header.puppies
                passthroughBehavior: when_no_match
                type: http
  ApiGatewayDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  ApiGatewayDeployment20250219:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  Stage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
       DeploymentId: !Ref ApiGatewayDeployment20250219
       RestApiId: !Ref Api
       StageName: prod
OpenAPI
{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "ParameterMappingExample",
    "version" : "2025-02-04T00:30:41Z"
  },
  "paths" : {
    "/pets" : {
      "get" : {
        "parameters" : [ {
          "name" : "puppies",
          "in" : "header",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "200 response"
          }
        },
        "x-amazon-apigateway-integration" : {
          "httpMethod" : "GET",
          "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "requestParameters" : {
            "integration.request.header.DogsAge0" : "method.request.header.puppies"
          },
          "passthroughBehavior" : "when_no_match",
          "type" : "http"
        }
      }
    }
  }
}

範例 2：將多個方法請求參數對應至不同的整合請求參數

下列範例會將多值方法請求查詢字串參數 methodRequestQueryParam 對應至整合請求查詢字串參數 integrationQueryParam，並將方法請求標頭參數 methodRequestHeaderParam 對應至整合請求路徑參數 integrationPathParam。

AWS Management Console
若要對應方法請求參數

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

  2. 選擇 REST API。

  3. 選擇一個方法。

    您的方法必須有非代理整合。

  4. 針對方法請求設定，選擇編輯。

  5. 選擇 URL 查詢字串參數。

  6. 選擇新增查詢字串。

  7. 對於名稱，輸入 methodRequestQueryParam。

  8. 選擇 HTTP 請求標頭。

  9. 選擇新增標頭。

  10. 對於名稱，輸入 methodRequestHeaderParam。

  11. 選擇儲存。

  12. 選擇整合請求索引標籤，然後針對整合請求設定，選擇編輯。

  13. 選擇 URL 路徑參數。

  14. 選擇新增路徑參數。

  15. 對於名稱，輸入 integrationPathParam。

  16. 對於映射自，輸入 method.request.header.methodRequestHeaderParam。

    這樣做會將您在方法請求中指定的方法請求標頭，對應至新的整合請求路徑參數。

  17. 選擇 URL 查詢字串參數。

  18. 選擇新增查詢字串。

  19. 對於名稱，輸入 integrationQueryParam。

  20. 對於映射自，輸入 method.request.multivaluequerystring.methodRequestQueryParam。

    這樣做會將多值查詢字串參數對應至新的單一值整合請求查詢字串參數。

  21. 選擇儲存。

  22. 重新部署 API 以使變更生效。

AWS CloudFormation

在此範例中，您使用 body 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。

以下 OpenAPI 定義會針對 HTTP 整合建立下列參數映射：

  • 將名為 methodRequestHeaderParam 的方法請求標頭對應到名為 integrationPathParam 的整合請求路徑參數

  • 將名為 methodRequestQueryParam 的多值方法請求查詢字串對應到名為 integrationQueryParam 的整合請求查詢字串

AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body: 
        openapi: 3.0.1
        info:
          title: Parameter mapping example 2
          version: "2025-01-15T19:12:31Z"
        paths:
          /:
            post:
              parameters:
                - name: methodRequestQueryParam
                  in: query
                  schema:
                    type: string
                - name: methodRequestHeaderParam
                  in: header
                  schema:
                    type: string
              responses:
                "200":
                  description: 200 response
              x-amazon-apigateway-integration:
                httpMethod: GET
                uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
                responses:
                  default:
                    statusCode: "200"
                requestParameters:
                  integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
                  integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
                requestTemplates:
                  application/json: '{"statusCode": 200}'
                passthroughBehavior: when_no_templates
                timeoutInMillis: 29000
                type: http
  ApiGatewayDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  ApiGatewayDeployment20250219:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  Stage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
       DeploymentId: !Ref ApiGatewayDeployment20250219
       RestApiId: !Ref Api
       StageName: prod
OpenAPI

以下 OpenAPI 定義會針對 HTTP 整合建立下列參數映射：

  • 將名為 methodRequestHeaderParam 的方法請求標頭對應到名為 integrationPathParam 的整合請求路徑參數

  • 將名為 methodRequestQueryParam 的多值方法請求查詢字串對應到名為 integrationQueryParam 的整合請求查詢字串

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Parameter mapping example 2",
    "version" : "2025-01-15T19:12:31Z"
  },
  "paths" : {
    "/" : {
      "post" : {
        "parameters" : [ {
          "name" : "methodRequestQueryParam",
          "in" : "query",
          "schema" : {
            "type" : "string"
          }
        }, {
          "name" : "methodRequestHeaderParam",
          "in" : "header",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "200 response"
          }
        },
        "x-amazon-apigateway-integration" : {
          "httpMethod" : "GET",
          "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "requestParameters" : {
            "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
            "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
          },
          "requestTemplates" : {
            "application/json" : "{\"statusCode\": 200}"
          },
          "passthroughBehavior" : "when_no_templates",
          "timeoutInMillis" : 29000,
          "type" : "http"
        }
      }
    }
  }
}

範例 3：將欄位從 JSON 請求內文對應至整合請求參數

您也可以使用 JSONPath 表達式，從 JSON 請求內文中的欄位對應整合請求參數。下列範例會將方法請求內文對應至名為 body-header 的整合請求標頭，並將部分請求內文 (如 JSON 表達式所示) 對應至名為 pet-price 的整合請求標頭。

若要測試此範例，請提供包含價格類別的輸入，如下所示：

[ 
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }
]
AWS Management Console
若要對應方法請求參數

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

  2. 選擇 REST API。

  3. 選擇 POST、PUT、PATCH 或 ANY 方法。

    您的方法必須有非代理整合。

  4. 針對整合請求設定，選擇編輯。

  5. 選擇 URL 請求標頭參數。

  6. 選擇新增請求標頭參數。

  7. 對於名稱，輸入 body-header。

  8. 對於映射自，輸入 method.request.body。

    這樣做會將方法請求內文對應至新的整合請求標頭參數。

  9. 選擇新增請求標頭參數。

  10. 對於名稱，輸入 pet-price。

  11. 對於映射自，輸入 method.request.body[0].price。

    這樣做會將部分方法請求內文對應至新的整合請求標頭參數。

  12. 選擇儲存。

  13. 重新部署 API 以使變更生效。

AWS CloudFormation

在此範例中，您使用 body 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。

AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body: 
        openapi: 3.0.1
        info:
          title: Parameter mapping example 3
          version: "2025-01-15T19:19:14Z"
        paths:
          /:
            post:
              responses:
                "200":
                  description: 200 response
              x-amazon-apigateway-integration:
                httpMethod: GET
                uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
                responses:
                  default:
                    statusCode: "200"
                requestParameters:
                  integration.request.header.pet-price: method.request.body[0].price
                  integration.request.header.body-header: method.request.body
                requestTemplates:
                  application/json: '{"statusCode": 200}'
                passthroughBehavior: when_no_templates
                timeoutInMillis: 29000
                type: http
  ApiGatewayDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  ApiGatewayDeployment20250219:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  Stage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
       DeploymentId: !Ref ApiGatewayDeployment20250219
       RestApiId: !Ref Api
       StageName: prod
OpenAPI

以下 OpenAPI 定義會從 JSON 請求內文中的欄位對應整合請求參數。

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Parameter mapping example 3",
    "version" : "2025-01-15T19:19:14Z"
  },
  "paths" : {
    "/" : {
      "post" : {
        "responses" : {
          "200" : {
            "description" : "200 response"
          }
        },
        "x-amazon-apigateway-integration" : {
          "httpMethod" : "GET",
          "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
          "responses" : {
            "default" : {
              "statusCode" : "200"
            }
          },
          "requestParameters" : {
            "integration.request.header.pet-price" : "method.request.body[0].price",
            "integration.request.header.body-header" : "method.request.body"
          },
          "requestTemplates" : {
            "application/json" : "{\"statusCode\": 200}"
          },
          "passthroughBehavior" : "when_no_templates",
          "timeoutInMillis" : 29000,
          "type" : "http"
        }
      }
    }
  }
}

範例 4：將整合回應對應至方法回應

您也可以將整合回應對應至方法回應。下列範例會將整合回應內文對應至名為 location 的方法回應標頭、將整合回應標頭 x-app-id 對應至方法回應標頭 id，並將多值整合回應標頭 item 對應至方法回應標頭 items。

AWS Management Console
若要對應整合回應

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

  2. 選擇 REST API。

  3. 選擇一個方法。

    您的方法必須有非代理整合。

  4. 選擇方法回應索引標籤，然後針對回應 200 選擇編輯。

  5. 針對標頭名稱，選擇新增標頭。

  6. 建立三個分別名為 id、item 和 location 的標頭。

  7. 選擇儲存。

  8. 選擇整合回應索引標籤，然後針對預設 - 回應選擇編輯。

  9. 在標頭映射下，輸入以下內容。

    1. 針對 id，輸入 integration.response.header.x-app-id

    2. 針對 item，輸入 integration.response.multivalueheader.item

    3. 針對 location，輸入 integration.response.body.redirect.url

  10. 選擇儲存。

  11. 重新部署 API 以使變更生效。

AWS CloudFormation

在此範例中，您使用 body 屬性將 OpenAPI 定義檔案匯入 API Gateway 中。

AWSTemplateFormatVersion: 2010-09-09
Resources:
  Api:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Body:
        openapi: 3.0.1
        info:
          title: Parameter mapping example
          version: "2025-01-15T19:21:35Z"
        paths:
          /:
            post:
              responses:
                "200":
                  description: 200 response
                  headers:
                    item:
                      schema:
                        type: string
                    location:
                      schema:
                        type: string
                    id:
                      schema:
                        type: string
              x-amazon-apigateway-integration:
                type: http
                httpMethod: GET
                uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
                responses:
                  default:
                    statusCode: "200"
                    responseParameters:
                      method.response.header.id: integration.response.header.x-app-id
                      method.response.header.location: integration.response.body.redirect.url
                      method.response.header.item: integration.response.multivalueheader.item
                requestTemplates:
                  application/json: '{"statusCode": 200}'
                passthroughBehavior: when_no_templates
                timeoutInMillis: 29000
  ApiGatewayDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  ApiGatewayDeployment20250219:
    Type: 'AWS::ApiGateway::Deployment'
    DependsOn: Api 
    Properties: 
      RestApiId: !Ref Api
  Stage:
    Type: 'AWS::ApiGateway::Stage'
    Properties:
       DeploymentId: !Ref ApiGatewayDeployment20250219
       RestApiId: !Ref Api
       StageName: prod
OpenAPI

以下 OpenAPI 定義會將整合回應對應至方法回應。

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Parameter mapping example",
    "version" : "2025-01-15T19:21:35Z"
  },
  "paths" : {
    "/" : {
      "post" : {
        "responses" : {
          "200" : {
            "description" : "200 response",
            "headers" : {
              "item" : {
                "schema" : {
                  "type" : "string"
                }
              },
              "location" : {
                "schema" : {
                  "type" : "string"
                }
              },
              "id" : {
                "schema" : {
                  "type" : "string"
                }
              }
            }
          }
        },
        "x-amazon-apigateway-integration" : {
          "type" : "http",
          "httpMethod" : "GET",
          "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
          "responses" : {
            "default" : {
              "statusCode" : "200",
              "responseParameters" : {
                "method.response.header.id" : "integration.response.header.x-app-id",
                "method.response.header.location" : "integration.response.body.redirect.url",
                "method.response.header.item" : "integration.response.multivalueheader.item"
              }
            }
          },
          "requestTemplates" : {
            "application/json" : "{\"statusCode\": 200}"
          },
          "passthroughBehavior" : "when_no_templates",
          "timeoutInMillis" : 29000
        }
      }
    }
  }
}