Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# 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 APIs in API Gateway](how-to-cors.md).
## 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 `DogsAge0`della richiesta di integrazione.
------
#### [ Console di gestione AWS ]
**Per mappare il parametro della richiesta di metodo**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere una REST API.
1. Scegliere un metodo.
Il metodo deve disporre di un’integrazione non proxy.
1. Per **Impostazioni della richiesta del metodo** scegliere **Modifica**.
1. Scegli **Intestazioni di richiesta HTTP**.
1. Seleziona **Add header (Aggiungi intestazione)**.
1. In **Nome**, inserisci **puppies**.
1. Scegli **Save** (Salva).
1. 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.
1. In **Nome**, inserisci **DogsAge0**.
1. Scegli **Save** (Salva).
1. 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**
1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. In Intestazioni, immetti **puppies:true**.
1. Scegli **Test (Esegui test)**.
1. 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere una REST API.
1. Scegliere un metodo.
Il metodo deve disporre di un’integrazione non proxy.
1. Per **Impostazioni della richiesta del metodo** scegliere **Modifica**.
1. Scegli **Parametri della stringa di query URL**.
1. Scegliere **Add query string (Aggiungi stringa di query)**.
1. In **Nome**, inserisci **methodRequestQueryParam**.
1. Scegli **Intestazioni di richiesta HTTP**.
1. Seleziona **Add header (Aggiungi intestazione)**.
1. In **Nome**, inserisci **methodRequestHeaderParam**.
1. Scegli **Save** (Salva).
1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** per **Impostazioni della richiesta di integrazione**.
1. Scegli **Parametri di percorso URL**.
1. Scegli **Aggiungi parametro di percorso**.
1. In **Nome**, inserisci **integrationPathParam**.
1. 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.
1. Scegli **Parametri della stringa di query URL**.
1. Scegliere **Add query string (Aggiungi stringa di query)**.
1. In **Nome**, inserisci **integrationQueryParam**.
1. 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.
1. Scegli **Save** (Salva).
1. Implementa nuovamente l'API per rendere effettive le modifiche.
------
#### [ CloudFormation ]
In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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 ](http://goessner.net/articles/JsonPath/index.html#e2) 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**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere una REST API.
1. Scegliere un metodo `POST`, `PUT`, `PATCH` o `ANY`.
Il metodo deve disporre di un’integrazione non proxy.
1. Per **Impostazioni della richiesta di integrazione**, scegliere **Modifica**.
1. Scegliere **Parametri delle intestazioni delle richieste URL**.
1. Scegliere **Aggiungi parametro dell’intestazione della richiesta**.
1. In **Nome**, inserisci **body-header**.
1. 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.
1. Scegliere **Aggiungi parametro dell’intestazione della richiesta**.
1. In **Nome**, inserisci **pet-price**.
1. 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.
1. Scegli **Save** (Salva).
1. Implementa nuovamente l'API per rendere effettive le modifiche.
------
#### [ CloudFormation ]
In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegliere una REST API.
1. Scegliere un metodo.
Il metodo deve disporre di un’integrazione non proxy.
1. Scegliere la scheda **Metodo di risposta**, quindi per **Risposta 200** scegliere **Modifica**.
1. Per **Nome intestazione**, scegliere **Aggiungi intestazione**.
1. Creare tre intestazioni denominate **id**, **item** e **location**.
1. Scegli **Save** (Salva).
1. Nella scheda **Risposta di integrazione** scegliere **Modifica** per **Predefinito - Risposta**.
1. In **Mappature intestazione** immettere i seguenti valori.
1. Per **id**, immettere **integration.response.header.x-app-id**
1. Per **elemento**, immettere **integration.response.multivalueheader.item**
1. Per **percorso**, immettere **integration.response.body.redirect.url**
1. Scegli **Save** (Salva).
1. Implementa nuovamente l'API per rendere effettive le modifiche.
------
#### [ CloudFormation ]
In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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
}
}
}
}
}
```
------