API Gateway 中 REST APIs參數映射範例

焦點模式

API Gateway 中 REST APIs參數映射範例 - Amazon API Gateway

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

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

範例 1：將方法請求參數映射至整合請求參數

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

AWS Management Console

映射方法請求參數

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇方法。

您的方法必須具有非代理整合。
針對方法請求設定，選擇編輯。
選擇 HTTP 請求標頭。
選擇新增標頭。
對於名稱，輸入 puppies。
選擇 Save (儲存)。
選擇整合請求索引標籤，然後針對整合請求設定，選擇編輯。

AWS Management Console 會自動puppies為您從新增參數映射method.request.header.puppies 至，但您需要變更名稱以符合整合端點預期的請求標頭參數。
對於名稱，輸入 DogsAge0。
選擇 Save (儲存)。
重新部署 API 以使變更生效。

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

（選用）測試參數映射

選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
針對標頭，輸入 puppies:true。
選擇測試。

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


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

在此範例中，您使用內文屬性將 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"
        }
      }
    }
  }
}

anchor anchor anchor

映射方法請求參數

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇方法。

您的方法必須具有非代理整合。
針對方法請求設定，選擇編輯。
選擇 HTTP 請求標頭。
選擇新增標頭。
對於名稱，輸入 puppies。
選擇 Save (儲存)。
選擇整合請求索引標籤，然後針對整合請求設定，選擇編輯。

AWS Management Console 會自動puppies為您從新增參數映射method.request.header.puppies 至，但您需要變更名稱以符合整合端點預期的請求標頭參數。
對於名稱，輸入 DogsAge0。
選擇 Save (儲存)。
重新部署 API 以使變更生效。

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

（選用）測試參數映射

選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。
針對標頭，輸入 puppies:true。
選擇測試。

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


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。

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

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

AWS Management Console

映射方法請求參數

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇方法。

您的方法必須具有非代理整合。
針對方法請求設定，選擇編輯。
選擇 URL 查詢字串參數。
選擇新增查詢字串。
對於名稱，輸入 methodRequestQueryParam。
選擇 HTTP 請求標頭。
選擇新增標頭。
對於名稱，輸入 methodRequestHeaderParam。
選擇 Save (儲存)。
選擇整合請求索引標籤，然後針對整合請求設定，選擇編輯。
選擇 URL 路徑參數。
選擇新增路徑參數。
對於名稱，輸入 integrationPathParam。
對於映射自，輸入 method.request.header.methodRequestHeaderParam。

這會將您在方法請求中指定的方法請求標頭映射至新的整合請求路徑參數。
選擇 URL 查詢字串參數。
選擇新增查詢字串。
對於名稱，輸入 integrationQueryParam。
對於映射自，輸入 method.request.multivaluequerystring.methodRequestQueryParam。

這會將多值查詢字串參數映射到新的單一值整合請求查詢字串參數。
選擇 Save (儲存)。
重新部署 API 以使變更生效。

AWS CloudFormation

在此範例中，您使用內文屬性將 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"
        }
      }
    }
  }
}

anchor anchor anchor

映射方法請求參數

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇方法。

您的方法必須具有非代理整合。
針對方法請求設定，選擇編輯。
選擇 URL 查詢字串參數。
選擇新增查詢字串。
對於名稱，輸入 methodRequestQueryParam。
選擇 HTTP 請求標頭。
選擇新增標頭。
對於名稱，輸入 methodRequestHeaderParam。
選擇 Save (儲存)。
選擇整合請求索引標籤，然後針對整合請求設定，選擇編輯。
選擇 URL 路徑參數。
選擇新增路徑參數。
對於名稱，輸入 integrationPathParam。
對於映射自，輸入 method.request.header.methodRequestHeaderParam。

這會將您在方法請求中指定的方法請求標頭映射至新的整合請求路徑參數。
選擇 URL 查詢字串參數。
選擇新增查詢字串。
對於名稱，輸入 integrationQueryParam。
對於映射自，輸入 method.request.multivaluequerystring.methodRequestQueryParam。

這會將多值查詢字串參數映射到新的單一值整合請求查詢字串參數。
選擇 Save (儲存)。
重新部署 API 以使變更生效。

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

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

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


[ 
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }
]

AWS Management Console

映射方法請求參數

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇 POST、PATCH、 PUT或 ANY方法。

您的方法必須具有非代理整合。
針對整合請求設定，選擇編輯。
選擇 URL 請求標頭參數。
選擇新增請求標頭參數。
對於名稱，輸入 body-header。
對於映射自，輸入 method.request.body。

這會將方法請求內文映射至新的整合請求標頭參數。
選擇新增請求標頭參數。
對於名稱，輸入 pet-price。
對於映射自，輸入 method.request.body[0].price。

這會將方法請求內文的一部分映射至新的整合請求標頭參數。
選擇 Save (儲存)。
重新部署 API 以使變更生效。

AWS CloudFormation

在此範例中，您使用內文屬性將 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"
        }
      }
    }
  }
}

anchor anchor anchor

映射方法請求參數

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇 POST、PATCH、 PUT或 ANY方法。

您的方法必須具有非代理整合。
針對整合請求設定，選擇編輯。
選擇 URL 請求標頭參數。
選擇新增請求標頭參數。
對於名稱，輸入 body-header。
對於映射自，輸入 method.request.body。

這會將方法請求內文映射至新的整合請求標頭參數。
選擇新增請求標頭參數。
對於名稱，輸入 pet-price。
對於映射自，輸入 method.request.body[0].price。

這會將方法請求內文的一部分映射至新的整合請求標頭參數。
選擇 Save (儲存)。
重新部署 API 以使變更生效。

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

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

AWS Management Console

映射整合回應

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇方法。

您的方法必須具有非代理整合。
選擇方法回應索引標籤，然後在回應 200 中選擇編輯。
針對標頭名稱，選擇新增標頭。
建立三個名為 id、 item和的標頭location。
選擇 Save (儲存)。
選擇整合回應索引標籤，然後針對預設 - 回應，選擇編輯。
在標頭映射下，輸入以下內容。
1. 針對 ID，輸入 integration.response.header.x-app-id
2. 針對項目，輸入 integration.response.multivalueheader.item
3. 針對位置，輸入 integration.response.body.redirect.url
選擇 Save (儲存)。
重新部署 API 以使變更生效。

AWS CloudFormation

在此範例中，您使用內文屬性將 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
        }
      }
    }
  }
}

anchor anchor anchor

映射整合回應

在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。
選擇 REST API。
選擇方法。

您的方法必須具有非代理整合。
選擇方法回應索引標籤，然後在回應 200 中選擇編輯。
針對標頭名稱，選擇新增標頭。
建立三個名為 id、 item和的標頭location。
選擇 Save (儲存)。
選擇整合回應索引標籤，然後針對預設 - 回應，選擇編輯。
在標頭映射下，輸入以下內容。
1. 針對 ID，輸入 integration.response.header.x-app-id
2. 針對項目，輸入 integration.response.multivalueheader.item
3. 針對位置，輸入 integration.response.body.redirect.url
選擇 Save (儲存)。
重新部署 API 以使變更生效。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

參數映射

參數映射來源參考

在本頁面

選取您的 Cookie 偏好設定

自訂 Cookie 偏好設定

必要

效能

功能

廣告

無法儲存 Cookie 偏好設定

API Gateway 中 REST APIs參數映射範例

範例 1：將方法請求參數映射至整合請求參數

映射方法請求參數

（選用）測試參數映射

映射方法請求參數

（選用）測試參數映射

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

映射方法請求參數

映射方法請求參數

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

映射方法請求參數

映射方法請求參數

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

映射整合回應

映射整合回應

在本頁面

Related resources

此頁面是否有幫助？

Related resources

下一個主題：

上一個主題：

需要協助？

選取您的 Cookie 偏好設定

API Gateway 中 REST APIs參數映射範例

範例 1：將方法請求參數映射至整合請求參數

映射方法請求參數

（選用） 測試參數映射

映射方法請求參數

（選用） 測試參數映射

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

映射方法請求參數

映射方法請求參數

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

映射方法請求參數

映射方法請求參數

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

映射整合回應

映射整合回應

在本頁面

Related resources

此頁面是否有幫助？

Related resources

下一個主題：

上一個主題：

需要協助？

（選用）測試參數映射

（選用）測試參數映射