Esempio 1: mappare un parametro della richiesta di metodo a un parametro della richiesta di integrazione Esempio 2: mappare più parametri di richiesta di metodo a diversi parametri di richiesta di integrazione Esempio 3: mappare i campi dal corpo della richiesta JSON ai parametri della richiesta di integrazione Esempio 4: mappare la risposta di integrazione alla risposta di metodo

Esempi di mappatura dei parametri per REST APIs in API Gateway

Gli esempi seguenti mostrano come creare espressioni di mappatura dei parametri utilizzando la console Gateway API, OpenAPI e modelli CloudFormation . Per un esempio di come utilizzare la mappatura dei parametri per creare le intestazioni CORS richieste, consultare CORS per REST API in Gateway API.

Esempio 1: mappare un parametro della richiesta di metodo a un parametro della richiesta di integrazione

L’esempio seguente mappa il parametro di intestazione puppies della richiesta di metodo al parametro di intestazione DogsAge0della richiesta di integrazione.

Console di gestione AWS

Per mappare il parametro della richiesta di metodo

Accedi alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.
Scegliere una REST API.
Scegliere un metodo.

Il metodo deve disporre di un’integrazione non proxy.
Per Impostazioni della richiesta del metodo scegliere Modifica.
Scegli Intestazioni di richiesta HTTP.
Seleziona Add header (Aggiungi intestazione).
Per Nome, immetti puppies.
Scegli Save (Salva).
Scegli la scheda Richiesta di integrazione, quindi seleziona Modifica per Impostazioni della richiesta di integrazione.

Aggiunge Console di gestione AWS automaticamente una mappatura dei parametri da method.request.header.puppies a puppies per te, ma devi modificare il nome in modo che corrisponda al parametro di intestazione della richiesta previsto dall'endpoint di integrazione.
Per Nome, immetti DogsAge0.
Scegli Save (Salva).
Implementa nuovamente l'API per rendere effettive le modifiche.

I passaggi seguenti mostrano come verificare che la mappatura dei parametri sia stata completata correttamente.

(Facoltativo) Test della mappatura dei parametri

Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
In Intestazioni, immetti puppies:true.
Scegli Test (Esegui test).

Nella sezione Log, il risultato sarà simile al seguente:


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}

Il parametro dell’intestazione della richiesta è cambiato da puppies a DogsAge0.

CloudFormation

In questo esempio, si utilizza la proprietà body per importare un file di definizione OpenAPI in Gateway API.


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"
        }
      }
    }
  }
}

Esempio 2: mappare più parametri di richiesta di metodo a diversi parametri di richiesta di integrazione

L’esempio seguente mappa il parametro della stringa di query della richiesta di metodo con più valori methodRequestQueryParam al parametro della stringa di query della richiesta di integrazione integrationQueryParam e mappa il parametro dell’intestazione della richiesta di metodo methodRequestHeaderParam al parametro del percorso della richiesta di integrazione integrationPathParam.

Console di gestione AWS

Per mappare i parametri della richiesta di metodo

Accedi alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.
Scegliere una REST API.
Scegliere un metodo.

Il metodo deve disporre di un’integrazione non proxy.
Per Impostazioni della richiesta del metodo scegliere Modifica.
Scegli Parametri della stringa di query URL.
Scegliere Add query string (Aggiungi stringa di query).
Per Nome, immetti methodRequestQueryParam.
Scegli Intestazioni di richiesta HTTP.
Seleziona Add header (Aggiungi intestazione).
Per Nome, immetti methodRequestHeaderParam.
Scegli Save (Salva).
Scegli la scheda Richiesta di integrazione, quindi seleziona Modifica per Impostazioni della richiesta di integrazione.
Scegli Parametri di percorso URL.
Scegli Aggiungi parametro di percorso.
Per Nome, immetti integrationPathParam.
In Mappato da, inserire method.request.header.methodRequestHeaderParam.

In questo modo l’intestazione della richiesta di metodo specificata nella richiesta di metodo viene mappata a un nuovo parametro del percorso della richiesta di integrazione.
Scegli Parametri della stringa di query URL.
Scegliere Add query string (Aggiungi stringa di query).
Per Nome, immetti integrationQueryParam.
In Mappato da, inserire method.request.multivaluequerystring.methodRequestQueryParam.

In questo modo il parametro della stringa di query con più valori viene mappato a un nuovo parametro della stringa di query della richiesta di integrazione a valore singolo.
Scegli Save (Salva).
Implementa nuovamente l'API per rendere effettive le modifiche.

CloudFormation

In questo esempio, si utilizza la proprietà body per importare un file di definizione OpenAPI in Gateway API.

La seguente definizione OpenAPI crea le mappature dei parametri per un’integrazione HTTP:

L’intestazione della richiesta di metodo methodRequestHeaderParam nel parametro di percorso della richiesta di integrazione integrationPathParam
La stringa di query della richiesta di metodo con più valori methodRequestQueryParam nella stringa di query della richiesta di integrazione 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

La seguente definizione OpenAPI crea le mappature dei parametri per un’integrazione HTTP:

L’intestazione della richiesta di metodo methodRequestHeaderParam nel parametro di percorso della richiesta di integrazione integrationPathParam
La stringa di query della richiesta di metodo con più valori methodRequestQueryParam nella stringa di query della richiesta di integrazione 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"
        }
      }
    }
  }
}

Esempio 3: mappare i campi dal corpo della richiesta JSON ai parametri della richiesta di integrazione

Puoi anche mappare i parametri della richiesta di integrazione dai campi del corpo della richiesta JSON utilizzando un'espressione. JSONPath L’esempio seguente mappa il corpo della richiesta di metodo a un’intestazione della richiesta di integrazione denominata body-header e mappa parte del corpo della richiesta, come indicato da un’espressione JSON, a un’intestazione della richiesta di integrazione denominata pet-price.

Per testare questo esempio è necessario fornire un input che contenga una categoria di prezzo, come la seguente:


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

Console di gestione AWS

Per mappare i parametri della richiesta di metodo

Accedi alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.
Scegliere una REST API.
Scegliere un metodo POST, PUT, PATCH o ANY.

Il metodo deve disporre di un’integrazione non proxy.
Per Impostazioni della richiesta di integrazione, scegliere Modifica.
Scegliere Parametri delle intestazioni delle richieste URL.
Scegliere Aggiungi parametro dell’intestazione della richiesta.
Per Nome, immetti body-header.
In Mappato da, inserire method.request.body.

In questo modo il corpo della richiesta di metodo viene mappato a un nuovo parametro di intestazione della richiesta di integrazione.
Scegliere Aggiungi parametro dell’intestazione della richiesta.
Per Nome, immetti pet-price.
In Mappato da, inserire method.request.body[0].price.

In questo modo una parte del corpo della richiesta di metodo viene mappata a un nuovo parametro di intestazione della richiesta di integrazione.
Scegli Save (Salva).
Implementa nuovamente l'API per rendere effettive le modifiche.

CloudFormation

In questo esempio, si utilizza la proprietà body per importare un file di definizione OpenAPI in Gateway API.


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

La seguente definizione OpenAPI mappa i parametri della richiesta di integrazione dai campi del corpo della richiesta 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"
        }
      }
    }
  }
}

Esempio 4: mappare la risposta di integrazione alla risposta di metodo

È anche possibile mappare la risposta di integrazione alla risposta di metodo. L’esempio seguente mappa il corpo della risposta di integrazione a un’intestazione della risposta di metodo denominata location, mappa l’intestazione della risposta di integrazione x-app-id all’intestazione della risposta di metodo e mappa l’intestazione id della risposta di integrazione con più valori item all’intestazione della risposta del metodo items.

Console di gestione AWS

Per mappare la risposta di integrazione

Accedi alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.
Scegliere una REST API.
Scegliere un metodo.

Il metodo deve disporre di un’integrazione non proxy.
Scegliere la scheda Metodo di risposta, quindi per Risposta 200 scegliere Modifica.
Per Nome intestazione, scegliere Aggiungi intestazione.
Creare tre intestazioni denominate id, item e location.
Scegli Save (Salva).
Nella scheda Risposta di integrazione scegliere Modifica per Predefinito - Risposta.
In Mappature intestazione immettere i seguenti valori.
1. Per id, immettere integration.response.header.x-app-id
2. Per elemento, immettere integration.response.multivalueheader.item
3. Per percorso, immettere integration.response.body.redirect.url
Scegli Save (Salva).
Implementa nuovamente l'API per rendere effettive le modifiche.

CloudFormation

In questo esempio, si utilizza la proprietà body per importare un file di definizione OpenAPI in Gateway API.


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

La definizione OpenAPI seguente mappa la risposta di integrazione alla risposta di metodo.


{
  "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
        }
      }
    }
  }
}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Mappatura dei parametri

Riferimento di origine per la mappatura dei parametri