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à.
# Trasformazioni dei dati per REST APIs in API Gateway
**Nota**
In questa sezione vengono illustrate le funzionalità da utilizzare con un’integrazione non proxy. Tuttavia, è consigliabile, ove possibile, usare un’integrazione proxy per la REST API. L’integrazione proxy ha una configurazione di integrazione più semplice e può evolvere con il backend senza annullare le impostazioni esistenti. Per ulteriori informazioni, consulta [Scegliere un tipo di integrazione API Gateway API](api-gateway-api-integration-types.md).
Se si utilizza un’integrazione non proxy, è possibile usare due funzionalità di Gateway API per trasformare la richiesta di metodo e la risposta di integrazione. È possibile trasformare la richiesta di metodo se utilizza un formato di payload diverso rispetto al payload della richiesta di integrazione. È possibile trasformare la risposta di integrazione se restituisce un formato di payload diverso da quello che deve essere restituito nella risposta di metodo. Per ulteriori informazioni sul ciclo di vita della richiesta, consultare [Risorsa di esempio per una REST API](rest-api-develop.md#rest-api-develop-example).
L’esempio seguente mostra una trasformazione di dati in cui per l’intestazione `"x-version:beta"`, il parametro di intestazione `x-version` viene trasformato nel parametro di intestazione `app-version`. La trasformazione di dati da `x-version` a `app-version` avviene nella richiesta di integrazione. In questo modo, l’endpoint di integrazione riceve il valore del parametro di intestazione trasformato. Quando l’endpoint di integrazione restituisce un codice di stato, il codice di stato viene trasformato da `200` a `204` prima della risposta di metodo.
![\[Diagramma della trasformazione di dati di Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/develop-non-proxy.png)
Per creare una trasformazione di dati, è possibile utilizzare le seguenti funzionalità:
**Mappatura dei parametri**
Nella mappatura dei parametri, è possibile modificare i parametri del percorso URL della richiesta di integrazione, i parametri della stringa di query URL o i valori dell’intestazione HTTP, ma non è possibile modificare il payload della richiesta di integrazione. È inoltre possibile modificare i valori dell’intestazione della risposta HTTP. La mappatura dei parametri si utilizza per creare valori di intestazione statici per CORS (Cross-Origin Resource Sharing).
È possibile utilizzare la mappatura dei parametri nella richiesta di integrazione per integrazioni proxy e non proxy, ma per usarla per una risposta di integrazione, è necessaria un’integrazione non proxy. La mappatura dei parametri non richiede script in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Per ulteriori informazioni, consulta [Mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping.md).
**Trasformazioni dei modelli di mappatura**
Nelle trasformazioni dei modelli di mappatura, si usa un modello di mappatura per mappare i parametri del percorso URL, i parametri della stringa di query URL, le intestazioni HTTP e la richiesta di integrazione o il corpo della risposta di integrazione. Un *modello di mappatura* è uno script espresso in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) utilizzando [JSONPath espressioni](https://goessner.net/articles/JsonPath/) e applicato al payload in base all'intestazione. `Content-type`
Con un modello di mappatura è possibile eseguire le seguenti operazioni:
+ Seleziona i dati da inviare utilizzando l'integrazione Servizi AWS, ad esempio le funzioni Amazon DynamoDB o Lambda o gli endpoint HTTP. Per ulteriori informazioni, consulta [Tutorial: modifica la richiesta e la risposta di integrazione per le integrazioni ai servizi AWS](set-up-data-transformations-in-api-gateway.md).
+ Sostituire in modo condizionale i parametri di richiesta e risposta di integrazione di un’API, creare nuovi valori di intestazione e sostituire i codici di stato. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md).
È anche possibile specificare il comportamento dell’API quando il corpo di una richiesta di integrazione ha un’intestazione `Content-type` senza modelli di mappatura corrispondenti. Questo processo è chiamato comportamento passthrough di integrazione. Per ulteriori informazioni, consulta [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md).
## Scelta tra mappatura dei parametri e trasformazioni dei modelli di mappatura
Quando possibile, è consigliabile utilizzare la mappatura dei parametri per trasformare i dati. Se l’API richiede la modifica del corpo o l’esecuzione di sostituzioni e modifiche condizionali in base alla richiesta o alla risposta di integrazione in entrata e non è possibile utilizzare un’integrazione proxy, si usano le trasformazioni dei modelli di mappatura.
# Mappatura dei parametri per REST APIs in API Gateway
**Nota**
Se si utilizza un’API HTTP, consultare [Trasformazione delle richieste e delle risposte API per API HTTP in Gateway API](http-api-parameter-mapping.md).
Nella mappatura dei parametri si mappano i parametri della richiesta o della risposta. È possibile mappare i parametri utilizzando valori statici o espressioni di mappatura dei parametri. Per l’elenco delle espressioni di mappatura, consultare [Riferimento alla fonte di mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping-sources.md). È possibile utilizzare la mappatura dei parametri nella richiesta di integrazione per integrazioni proxy e non proxy, ma per usarla per una risposta di integrazione, è necessaria un’integrazione non proxy.
Ad esempio, è possibile mappare il parametro di intestazione della richiesta di metodo `puppies` al parametro di intestazione della richiesta di integrazione `DogsAge0`. Quindi, se un client invia l’intestazione `puppies:true` all’API, la richiesta di integrazione invia l’intestazione della richiesta `DogsAge0:true` all’endpoint di integrazione. Nel diagramma seguente viene illustrato il ciclo di vita della richiesta di questo esempio.
![\[Diagramma dell’esempio di mappatura dei parametri di Gateway API per una richiesta\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
Per eseguire questo esempio utilizzando Gateway API, consultare [Esempio 1: mappare un parametro della richiesta di metodo a un parametro della richiesta di integrazione](request-response-data-mappings.md#request-response-data-mappings-example-1).
Inoltre, è possibile mappare il parametro di intestazione `kittens` della risposta di integrazione al parametro di intestazione `CatsAge0` della risposta di metodo. Quindi, se l’endpoint di integrazione restituisce `kittens:false`, il client riceve l’intestazione `CatsAge0:false`. Nel diagramma seguente viene illustrato il ciclo di vita della richiesta di questo esempio.
![\[Diagramma dell’esempio di mappatura dei parametri di Gateway API per una risposta\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [Esempi di mappatura dei parametri per REST APIs in API Gateway](request-response-data-mappings.md)
+ [Riferimento alla fonte di mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping-sources.md)
# 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
}
}
}
}
}
```
------
# Riferimento alla fonte di mappatura dei parametri per REST APIs in API Gateway
Quando si crea una mappatura dei parametri, è possibile specificare i parametri della richiesta di metodo o della risposta di integrazione da modificare e le modalità con cui si desidera modificare tali parametri.
La tabella seguente mostra i parametri della richiesta di metodo che è possibile mappare e l’espressione per creare la mappatura. In queste espressioni, *name* è il nome di un parametro di richiesta del metodo. Ad esempio, per mappare il parametro dell’intestazione della richiesta `puppies`, si utilizza l’espressione `method.request.header.puppies`. L’espressione deve corrispondere all’espressione regolare `'^[a-zA-Z0-9._$-]+$]'`. È possibile utilizzare la mappatura dei parametri nella richiesta di integrazione per le integrazioni proxy e non proxy.
| **Origine dati mappata** | **Espressione di mappatura** |
| --- | --- |
| Percorso della richiesta di metodo | method.request.path.name |
| Stringa di query della richiesta di metodo | method.request.querystring.name |
| Stringa di query multi-valore della richiesta del metodo | method.request.multivaluequerystring.name |
| Intestazione della richiesta di metodo | method.request.header.name |
| Intestazione multi-valore della richiesta di metodo | method.request.multivalueheader.name |
| Corpo della richiesta di metodo | method.request.body |
| Corpo della richiesta del metodo (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*è un' JSONPath espressione per un campo JSON del corpo di una richiesta. Per ulteriori informazioni, vedere [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variabili di fase | stageVariables.name |
| Variabili di contesto | `context.name` Il nome deve essere una delle [variabili di contesto supportate](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valore statico | `'static_value'`. La *static\$1value* è una stringa letterale e deve essere racchiusa tra virgolette singole. Ad esempio, `'https://www.example.com'`. |
La tabella seguente mostra i parametri della risposta di integrazione che è possibile mappare e l’espressione per creare la mappatura. In queste espressioni, *name* è il nome di un parametro di risposta di integrazione. È possibile mappare le intestazioni della risposta di metodo da qualsiasi intestazione o corpo della risposta di integrazione, variabili \$1context o valori statici. Per utilizzare la mappatura dei parametri per una risposta di integrazione, è necessaria un’integrazione non proxy.
| Origine dati mappata | Espressione di mappatura |
| --- | --- |
| Intestazione della risposta di integrazione | integration.response.header.name |
| Intestazione della risposta di integrazione | integration.response.multivalueheader.name |
| Corpo della risposta di integrazione | integration.response.body |
| Corpo della risposta di integrazione (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*è un' JSONPath espressione per un campo JSON del corpo di una risposta. Per ulteriori informazioni, vedere [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variabile di fase | stageVariables.name |
| Variabile di contesto | `context.name` Il nome deve essere una delle [variabili di contesto supportate](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valore statico | ` 'static_value'` La *static\$1value* è una stringa letterale e deve essere racchiusa tra virgolette singole. Ad esempio, `'https://www.example.com'`. |
# Trasformazioni dei modelli di mappatura per REST APIs in API Gateway
Una trasformazione del modello di mappatura utilizza un modello di mappatura per modificare la richiesta o la risposta di integrazione. Un *modello di mappatura* è uno script espresso in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e applicato a un payload utilizzando un codice basato sull'intestazione. [JSONPath ](https://goessner.net/articles/JsonPath/)`Content-type` Si utilizzano i modelli di mappatura per le trasformazioni dei modelli di mappatura. Questa sezione descrive le informazioni concettuali relative ai modelli di mappatura.
Il diagramma seguente mostra il ciclo di vita della richiesta per una `POST /pets` risorsa che ha un'integrazione con un endpoint di integrazione. PetStore In questa API, un utente invia i dati su un animale domestico e l’endpoint di integrazione restituisce la tariffa di adozione associata all’animale domestico. In questo ciclo di vita della richiesta, le trasformazioni dei modelli di mappatura filtrano il corpo della richiesta all’endpoint di integrazione e il corpo della risposta dall’endpoint di integrazione.
![\[Esempio di ciclo di vita della richiesta\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/mapping-template-transforms.png)
Le sezioni seguenti illustrano il ciclo di vita della richiesta e della risposta.
## Richiesta di metodo e richiesta di integrazione
Nell’esempio precedente, se il corpo della richiesta inviato alla richiesta di metodo è:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
Questo corpo della richiesta non è nel formato corretto per essere utilizzato dall’endpoint di integrazione, pertanto Gateway API esegue una trasformazione del modello di mappatura. Gateway API esegue solo una trasformazione del modello di mappatura perché esiste un modello di mappatura definito per Content-Type `application/json`. Se non si definisce un modello di mappatura per Content-Type, per impostazione predefinita, Gateway API passa il corpo all’endpoint di integrazione tramite la richiesta di integrazione. Per modificare questo comportamento, consultare [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md).
Il seguente modello di mappatura trasforma i dati della richiesta di metodo nella richiesta di integrazione prima che vengano inviati all’endpoint di integrazione:
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. La variabile `$inputRoot` rappresenta l'oggetto radice nei dati JSON originali della sezione precedente. Le direttive iniziano con il simbolo `#`.
1. `dog` è una concatenazione di `id` dell’utente e di un valore di stringa.
1. `Age` proviene dal corpo della richiesta di metodo.
Quindi, il seguente output viene inoltrato all’endpoint di integrazione:
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## Risposta di integrazione e risposta di metodo
Dopo l’esito positivo della richiesta all’endpoint di integrazione, l’endpoint invia una risposta alla risposta di integrazione di Gateway API. L’esempio seguente indica i dati di output di un endpoint di integrazione:
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
La risposta di metodo prevede un payload diverso da quello restituito dalla risposta di integrazione. Gateway API esegue una trasformazione del modello di mappatura. Gateway API esegue solo una trasformazione del modello di mappatura perché esiste un modello di mappatura definito per Content-Type `application/json`. Se non si definisce un modello di mappatura per Content-Type, per impostazione predefinita, Gateway API passa il corpo alla risposta di metodo tramite la risposta di integrazione. Per modificare questo comportamento, consultare [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md).
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
Il seguente output viene inviato alla risposta di metodo:
```
{"adoptionFee": 19.95}
```
L’esempio di trasformazione del modello di mappatura è completato. Se possibile, anziché utilizzare trasformazioni di modelli di mappatura, è consigliabile un’integrazione proxy per trasformare i dati. Per ulteriori informazioni, consulta [Scegliere un tipo di integrazione API Gateway API](api-gateway-api-integration-types.md).
# Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway
Se la richiesta di metodo ha un payload senza modello di mappatura definito per l’intestazione `Content-Type`, è possibile scegliere di passare il payload della richiesta fornito dal client tramite la richiesta di integrazione al backend senza trasformazione. Il processo è noto come passthrough di integrazione.
L’effettivo comportamento del passthrough di una richiesta in entrata è determinato da questa impostazione. Sono disponibili tre opzioni:
**Opzione Quando nessun modello corrisponde all'intestazione Content-Type della richiesta**
Selezionare questa opzione se si desidera che venga eseguito il passthrough del corpo della richiesta di metodo nella richiesta di integrazione al back-end senza trasformazione quando il tipo di contenuto della richiesta di metodo non corrisponde ai tipi di contenuto associati ai modelli di mappatura.
Durante la chiamata all'API Gateway API, scegli questa opzione impostando `WHEN_NO_MATCH` come valore della proprietà `passthroughBehavior` in [Integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Quando non ci sono modelli definiti (consigliato)**
Selezionare questa opzione se si desidera che venga eseguito il passthrough del corpo della richiesta di metodo nella richiesta di integrazione al back-end senza trasformazione quando nella richiesta di integrazione non è stato definito un modello di mappatura. Se viene definito un modello con questa opzione selezionata, la richiesta di metodo con un payload e un tipo di contenuto che non corrispondono ad alcun modello di mappatura definito verrà rifiutata con una risposta HTTP 415 Tipo di supporto non compatibile.
Durante la chiamata all'API Gateway API, scegli questa opzione impostando `WHEN_NO_TEMPLATES` come valore della proprietà `passthroughBehavior` in [Integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Mai**
Selezionare questa opzione se non si desidera che venga eseguito il passthrough del corpo della richiesta di metodo nella richiesta di integrazione al back-end senza trasformazione quando nella richiesta di integrazione non è stato definito un modello di mappatura. Se viene definito un modello al momento della selezione di questa opzione, la richiesta di metodo di un tipo di contenuto non mappato sarà rifiutata con la risposta Tipo di supporto non supportato HTTP 415.
Durante la chiamata all'API Gateway API, scegli questa opzione impostando `NEVER` come valore della proprietà `passthroughBehavior` in [Integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
Gli esempi seguenti illustrano i possibili comportamenti del passthrough.
Esempio 1: viene definito un modello di mappatura nella richiesta di integrazione per il tipo di contenuto `application/json`.
| Content-type | Opzione passthrough | Comportamento |
| --- | --- | --- |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1MATCH | Il payload della richiesta viene trasformato utilizzando il modello. |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta viene trasformato utilizzando il modello. |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | NEVER | Il payload della richiesta viene trasformato utilizzando il modello. |
| application/json | WHEN\$1NO\$1MATCH | Il payload della richiesta viene trasformato utilizzando il modello. |
| application/json | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta viene trasformato utilizzando il modello. |
| application/json | NEVER | Il payload della richiesta viene trasformato utilizzando il modello. |
| application/xml | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
| application/xml | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
Esempio 2: viene definito un modello di mappatura nella richiesta di integrazione per il tipo di contenuto `application/xml`.
| Content-type | Opzione passthrough | Comportamento |
| --- | --- | --- |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1TEMPLATES | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| application/json | WHEN\$1NO\$1TEMPLATES | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
| application/json | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | Il payload della richiesta viene trasformato utilizzando il modello. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta viene trasformato utilizzando il modello. |
| application/xml | NEVER | Il payload della richiesta viene trasformato utilizzando il modello. |
Esempio 3: nessun modello di mappatura viene definito nella richiesta di integrazione
| Content-type | Opzione passthrough | Comportamento |
| --- | --- | --- |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| application/json | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| application/json | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. |
| application/xml | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. |
# Esempio di modello di mappatura aggiuntivo per REST APIs in API Gateway
L’esempio seguente mostra un’API per album fotografico in Gateway API che utilizza modelli di mappatura per trasformare i dati delle richieste e delle risposte di integrazione. Utilizza anche modelli di dati per definire i payload della richiesta di metodo e della risposta di integrazione. Per ulteriori informazioni sui modelli di dati, consulta [Modelli di dati per REST APIs](models-mappings-models.md).
## Richiesta di metodo e richiesta di integrazione
Di seguito è riportato un modello che definisce il corpo della richiesta di metodo. Questo modello di input richiede che il chiamante carichi una pagina di foto con un minimo di 10 foto per ogni pagina. È possibile utilizzare questo modello di input per generare un SDK o per usare la convalida della richiesta per l’API. Quando si utilizza la convalida della richiesta, se il corpo della richiesta di metodo non aderisce alla struttura dei dati del modello, Gateway API non esegue la richiesta.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
Di seguito è riportato un esempio di corpo della richiesta di metodo che aderisce alla struttura dei dati del modello di dati precedente.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
In questo esempio, quando il corpo della richiesta di metodo precedente viene inviato dal client, il modello di mappatura trasforma il payload in modo che corrisponda al formato richiesto dall’endpoint di integrazione.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
L’esempio seguente fornisce i dati di output della trasformazione:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Questi dati vengono inviati alla richiesta di integrazione e quindi all’endpoint di integrazione.
## Risposta di integrazione e risposta di metodo
Di seguito è riportato un esempio di modello di output per i dati delle foto dall’endpoint di integrazione. È possibile utilizzare questo metodo per un modello di risposta del metodo, che è necessario quando si genera un SDK tipizzato in modo sicuro per l'API. Ciò garantisce che l'output venga trasmesso in una classe appropriata in Java o Objective-C.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
L’endpoint di integrazione potrebbe non generare una risposta che aderisce alla struttura dei dati di questo modello. Ad esempio, la risposta di integrazione potrebbe essere simile alla seguente:
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
Il modello di mappatura di esempio seguente trasforma i dati della risposta di integrazione nel formato previsto dalla risposta di metodo:
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
L’esempio seguente fornisce i dati di output della trasformazione:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Questi dati vengono inviati alla risposta di metodo e quindi nuovamente al client.
# Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway
È possibile utilizzare le trasformazioni dei modelli di mappatura per sostituire qualsiasi tipo di parametro della richiesta, intestazione della risposta o codice di stato della risposta. Per utilizzare il modello di mappatura:
+ Esegui mappature many-to-one dei parametri
+ Sostituire i parametri dopo l'applicazione delle mappature standard di Gateway API
+ Mappare i parametri in modo condizionale in base al contenuto del corpo o ad altri valori dei parametri
+ Creare nuovi parametri in modo programmatico
+ Sostituire i codici di stato restituiti dall'endpoint di integrazione
Le sovrascritture sono finali. Una sovrascrittura può essere applicata a ciascun parametro una sola volta. Se si prova a sovrascrivere lo stesso parametro più volte, Gateway API restituisce una risposta `5XX`. Se occorre sovrascrivere lo stesso parametro più volte in tutto il modello, ti consigliamo di creare una variabile e applicare la sovrascrittura alla fine del modello. Il modello viene applicato solo dopo che l'intero modello è stato analizzato.
## Esempio 1: sostituire il codice di stato in base al corpo di integrazione
L’esempio seguente utilizza l’[API di esempio](api-gateway-create-api-from-example.md) per sostituire il codice di stato in base al corpo della risposta di integrazione.
------
#### [ Console di gestione AWS ]
**Per sostituire un codice di stato in base al corpo della risposta di integrazione**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Seleziona **Create API** (Crea API).
1. Per **API REST**, scegliere **Crea**.
1. Per **Dettagli API**, scegliere **API di esempio**.
1. Seleziona **Create API** (Crea API).
Gateway API crea un’API PetStore di esempio. Per recuperare le informazioni su un animale domestico, si utilizza la richiesta di metodo dell’API `GET /pets/{petId}`, dove `{petId}` è un parametro di percorso corrispondente al numero ID di un animale domestico.
In questo esempio, si sostituisce il codice di risposta del metodo `GET` con `400` quando viene rilevata una condizione di errore.
1. Nella struttura **Risorse**, scegli il metodo `GET` in `/{petId}`.
1. Innanzitutto, esegui il test dell’attuale implementazione dell’API.
Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. Per **petId** immetti **-1**, quindi seleziona **Test**.
Il **corpo della risposta indica** un errore: out-of-range
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Inoltre, l’ultima riga nella sezione **Log** termina con: `Method completed with status: 200`.
L’integrazione è stata completata, ma si è verificato un errore. Ora si sostituisce il codice di stato in base alla risposta di integrazione.
1. Nella scheda **Risposta di integrazione** scegli **Modifica** per **Predefinito - Risposta**.
1. Scegli **Modelli di mappatura**.
1. Scegliere **Add mapping template (Aggiungi modello di mappatura)**.
1. Per **Tipo di contenuto** inserisci **application/json**.
1. Per **Corpo del modello** inserisci quanto segue:
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Questo modello di mappatura utilizza la variabile `$context.responseOverride.status` per sostituire il codice di stato con `400` se la risposta di integrazione contiene la stringa `error`.
1. Scegli **Save** (Salva).
1. Seleziona la scheda **Test**.
1. Per **petId** immetti **-1**.
1. Nei risultati, il **Response Body** indica un out-of-range errore:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Tuttavia, l’ultima riga nella sezione **Log** termina ora con: `Method completed with status: 400`.
------
#### [ 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: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
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 la risorsa `GET pets/{petId}` e sostituisce il codice di stato in base al corpo di integrazione.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Esempio 2: sostituire l’intestazione della richiesta e creare nuove intestazioni
L’esempio seguente utilizza l’[API di esempio](api-gateway-create-api-from-example.md) per sostituire l’intestazione della richiesta e creare nuove intestazioni.
------
#### [ Console di gestione AWS ]
**Per sostituire un’intestazione della richiesta di metodo creando una nuova intestazione**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Scegli l’API di esempio creata nel tutorial precedente. Il nome dell'API dovrebbe essere. **PetStore**
1. Nella struttura **Risorse**, scegli il metodo `GET` in `/pet`.
1. Nella scheda **Richiesta metodo** scegli **Modifica** in **Impostazioni della richiesta del metodo**.
1. Scegli **Intestazioni di richiesta HTTP**, quindi seleziona **Aggiungi intestazione**.
1. In **Nome**, inserisci **header1**.
1. Scegli **Aggiungi intestazione**, quindi crea una seconda intestazione chiamata **header2**.
1. Scegli **Save** (Salva).
Ora, si combinano queste intestazioni in un unico valore di intestazione utilizzando un modello di mappatura.
1. Nella scheda **Richiesta di integrazione** seleziona **Modifica** per **Impostazioni della richiesta di integrazione**.
1. Per **Richiesta corpo passthrough** scegli **Quando non ci sono modelli definiti (consigliato)**.
1. Scegli **Modelli di mappatura** e procedi come indicato di seguito:
1. Scegliere **Add mapping template (Aggiungi modello di mappatura)**.
1. Per **Tipo di contenuto** inserisci **application/json**.
1. Per **Corpo del modello** inserisci quanto segue:
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
Questo modello di mappatura sostituisce `header1` con la stringa `pets` e crea un’intestazione con più valori chiamata `$header3Value` che combina `header1` e `header2`.
1. Scegli **Save** (Salva).
1. Seleziona la scheda **Test**.
1. In **Intestazioni**, copiare il codice seguente:
```
header1:header1Val
header2:header2Val
```
1. Scegli **Test (Esegui test)**.
Nella sezione **Log** è presente una voce che include questo testo:
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ 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: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
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 la risorsa `GET pets`, sostituisce l’intestazione della richiesta e crea nuove intestazioni.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Per utilizzare la sostituzione di un modello di mappatura, si aggiunge una o più delle seguenti variabili `$context`. Per l’elenco delle variabili `$context`, consultare [Variabili di contesto per le trasformazioni dei dati](api-gateway-mapping-template-reference.md#context-variable-reference).
# Tutorial: modifica la richiesta e la risposta di integrazione per le integrazioni ai servizi AWS
Il seguente tutorial mostra come utilizzare le trasformazioni dei modelli di mappatura per configurare i modelli di mappatura per trasformare le richieste e le risposte di integrazione utilizzando la console e la CLI. AWS
**Topics**
+ [Configurare la trasformazione dei dati utilizzando la console Gateway Amazon API](#mapping-example-console)
+ [Configura la trasformazione dei dati utilizzando la AWS CLI](#mapping-example-cli)
+ [CloudFormation Modello di trasformazione dei dati completato](#api-gateway-data-transformations-full-cfn-stack)
## Configurare la trasformazione dei dati utilizzando la console Gateway Amazon API
[In questo tutorial, creerai un'API incompleta e una tabella DynamoDB utilizzando il seguente file.zip .zip. data-transformation-tutorial-console](samples/data-transformation-tutorial-console.zip) Questa API incompleta dispone di una risorsa `/pets` con i metodi `GET` e `POST`.
+ Il metodo `GET` otterrà i dati dall'endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. I dati di output verranno trasformati in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md).
+ Il metodo `POST` consentirà all'utente di pubblicare (`POST`) le informazioni sugli animali domestici in una tabella Amazon DynamoDB utilizzando un modello di mappatura.
Scarica e decomprimi il modello di creazione [dell'](samples/data-transformation-tutorial-console.zip)app per. CloudFormation Verrà utilizzato questo modello per creare una tabella DynamoDB per pubblicare informazioni sugli animali domestici e un'API incompleta. Il resto della procedura verrà completato nella console Gateway Amazon API.
**Per creare una pila CloudFormation**
1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Scegliere **Create stack (Crea stack)**, quindi **With new resources (standard) (Con nuove risorse (standard))**.
1. In **Specificare modello**, scegliere **Carica un file modello**.
1. Selezionare il modello scaricato.
1. Scegli **Next (Successivo)**.
1. Per **Stack name (Nome stack)**, inserire **data-transformation-tutorial-console**, quindi scegliere **Next (Avanti)**.
1. Per **Configure stack options (Configura opzioni di stack)**, scegliere **Next (Successivo)**.
1. Per quanto riguarda **le funzionalità**, riconosci che CloudFormation puoi creare risorse IAM nel tuo account.
1. Scegli **Avanti**, quindi scegli **Invia**.
CloudFormation fornisce le risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Quando lo stato del tuo CloudFormation stack è **CREATE\$1COMPLETE**, sei pronto per passare alla fase successiva.
**Test della risposta di integrazione `GET`**
1. Nella scheda **Risorse** dello CloudFormation stack di**data-transformation-tutorial-console**, seleziona l'ID fisico della tua API.
1. Nel pannello di navigazione principale scegli **Risorse**, quindi seleziona il metodo **GET**.
1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
L'output del test mostrerà quanto segue:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Questo output verrà trasformato in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md).
**Trasformazione della risposta di integrazione `GET`**
1. Scegli la scheda **Risposta di integrazione**.
Attualmente non sono definiti modelli di mappatura, quindi la risposta di integrazione non verrà trasformata.
1. Per **Predefinito - Risposta** scegli **Modifica**.
1. Scegli **Modelli di mappatura** e procedi come indicato di seguito:
1. Scegliere **Add mapping template (Aggiungi modello di mappatura)**.
1. Per **Tipo di contenuto** inserisci **application/json**.
1. Per **Corpo del modello** inserisci quanto segue:
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
Scegli **Save** (Salva).
**Test della risposta di integrazione `GET`**
+ Scegli la scheda **Test**, quindi seleziona **Test**.
L'output del test mostrerà la risposta trasformata.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Trasformazione dei dati di input dal metodo `POST`**
1. Scegli il metodo **POST**.
1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** per **Impostazioni della richiesta di integrazione**.
Il CloudFormation modello ha compilato alcuni campi di richiesta di integrazione.
+ Il tipo di integrazione è Servizio AWS.
+ Servizio AWS Si tratta di DynamoDB.
+ Il metodo HTTP è `POST`.
+ L'operazione è `PutItem`.
+ Il ruolo di esecuzione che consente ad API Gateway di inserire un elemento nella tabella DynamoDB è. `data-transformation-tutorial-console-APIGatewayRole` CloudFormation ha creato questo ruolo per consentire ad API Gateway di disporre delle autorizzazioni minime per interagire con DynamoDB.
Il nome della tabella DynamoDB non è stato specificato. Il nome verrà specificato nei passaggi seguenti.
1. Per **Richiesta corpo passthrough** seleziona **Mai**.
Ciò significa che l'API rifiuterà i dati con Content-Types che non dispongono di un modello di mappatura.
1. Scegli **Modelli di mappatura**.
1. **Tipo di contenuto** è impostato su `application/json`. Ciò significa che i tipi di contenuto che non lo sono application/json verranno rifiutati dall'API. Per ulteriori informazioni sui comportamenti passthrough di integrazione, consultare [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md).
1. Inserire il codice seguente nell'editor di testo.
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
Questo modello specifica la tabella come `data-transformation-tutorial-console-ddb` e imposta gli elementi come `id`, `type` e`price`. Gli elementi proverranno dal corpo del metodo `POST`. È anche possibile utilizzare un modello di dati per creare un modello di mappatura. Per ulteriori informazioni, consulta [Richiedi la convalida per REST APIs in API Gateway](api-gateway-method-request-validation.md).
1. Scegliere il pulsante **Salva** per salvare il modello di mappatura.
**Aggiunta di un metodo e una risposta di integrazione dal metodo `POST`**
Hanno CloudFormation creato un metodo vuoto e una risposta di integrazione. Questa risposta verrà modificata per fornire ulteriori informazioni. Per ulteriori informazioni su come modificare le risposte, consultare [Esempi di mappatura dei parametri per REST APIs in API Gateway](request-response-data-mappings.md).
1. Nella scheda **Risposta di integrazione** scegli **Modifica** per **Predefinito - Risposta**.
1. Scegli **Modelli di mappatura**, quindi seleziona **Aggiungi modello di mappatura**.
1. Per **Content-type** immetti **application/json**.
1. Nell'editor di codice, inserire il seguente modello di mappatura di output per inviare un messaggio di output:
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
Per ulteriori informazioni sulle variabili di contesto, consultare [Variabili di contesto per le trasformazioni dei dati](api-gateway-mapping-template-reference.md#context-variable-reference).
1. Scegliere il pulsante **Salva** per salvare il modello di mappatura.
**Test del metodo `POST`**
Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
1. Nel corpo della richiesta, inserire il seguente esempio.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. Scegli **Test (Esegui test)**.
L'output dovrebbe mostrare il messaggio di operazione riuscita.
Puoi aprire la console DynamoDB [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)all'indirizzo per verificare che l'elemento di esempio sia nella tua tabella.
**Per eliminare uno stack CloudFormation**
1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Seleziona il tuo stack. CloudFormation
1. Scegli **Elimina** e conferma la tua scelta.
## Configura la trasformazione dei dati utilizzando la AWS CLI
[In questo tutorial, creerai un'API incompleta e una tabella DynamoDB utilizzando il seguente file.zip .zip. data-transformation-tutorial-cli](samples/data-transformation-tutorial-cli.zip) Questa API incompleta dispone di una risorsa `/pets` con un metodo `GET` integrato con l'endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Verrà creato un metodo `POST` per connettersi a una tabella DynamoDB e si useranno modelli di mappatura per inserire dati in una tabella DynamoDB.
+ I dati di output verranno quindi trasformati in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md).
+ Verrà creato un metodo `POST` per consentire all'utente di pubblicare (`POST`) le informazioni sugli animali domestici in una tabella Amazon DynamoDB utilizzando un modello di mappatura.
**Per creare uno stack CloudFormation**
Scarica e decomprimi [il modello di creazione dell'app](samples/data-transformation-tutorial-cli.zip) per. CloudFormation
Per completare il tutorial seguente, è necessario disporre della [AWS Command Line Interface (AWS CLI) versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Per i comandi lunghi viene utilizzato un carattere di escape (`\`) per dividere un comando su più righe.
**Nota**
In Windows, alcuni comandi della CLI Bash utilizzati comunemente (ad esempio, `zip`) non sono supportati dai terminali integrati del sistema operativo. Per ottenere una versione integrata su Windows di Ubuntu e Bash, [installa il sottosistema Windows per Linux](https://learn.microsoft.com/en-us/windows/wsl/install). I comandi della CLI di esempio in questa guida utilizzano la formattazione Linux. Se si utilizza la CLI di Windows, i comandi che includono documenti JSON in linea dovranno essere riformattati.
1. Usa il seguente comando per creare lo CloudFormation stack.
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation fornisce le risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Usa il comando seguente per vedere lo stato del tuo CloudFormation stack.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. Quando lo stato dello CloudFormation stack è`StackStatus: "CREATE_COMPLETE"`, usa il seguente comando per recuperare i valori di output pertinenti per i passaggi futuri.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Di seguito sono riportati i valori di output:
+ ApiRole, che è il nome del ruolo che consente ad API Gateway di inserire elementi nella tabella DynamoDB. Per questo tutorial, il nome del ruolo è `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`.
+ DDBTableNome, che è il nome della tabella DynamoDB. Per questo tutorial il nome della tabella è `data-transformation-tutorial-cli-ddb`.
+ ResourceId, che è l'ID della risorsa pets in cui sono esposti i `POST` metodi `GET` and. Per questo tutorial, l'ID risorsa è `efg456`.
+ ApiId, che è l'ID dell'API. Per questo tutorial, l'ID API è `abc123`.
**Test del metodo `GET` prima della trasformazione dei dati**
+ Utilizzare il seguente comando per eseguire il test del metodo `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
L'output del test riporterà le seguenti informazioni.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Questo output verrà trasformato in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md).
**Trasformazione della risposta di integrazione `GET`**
+ Utilizzare il comando seguente per aggiornare una risposta di integrazione per il metodo `GET`. Sostituisci *rest-api-id* e *resource-id* con i tuoi valori.
Per creare una risposta di integrazione, utilizzare il comando seguente.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**Test del metodo `GET`**
+ Utilizzare il seguente comando per eseguire il test del metodo `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
L'output del test mostrerà la risposta trasformata.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Creazione di un metodo `POST`**
1. Utilizzare il seguente comando per creare un nuovo metodo nella risorsa `/pets`.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
Questo metodo ti consentirà di inviare informazioni sugli animali domestici alla tabella DynamoDB che hai creato nello stack. CloudFormation
1. Utilizzate il seguente comando per creare un' Servizio AWS integrazione sul metodo. `POST`
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. Utilizzare il comando seguente per creare una risposta del metodo per una corretta chiamata del metodo `POST`.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Utilizzare il comando seguente per creare una risposta dell'integrazione per una corretta chiamata del metodo `POST`.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**Test del metodo `POST`**
+ Utilizzare il seguente comando per eseguire il test del metodo `POST`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
L'output mostrerà il messaggio di operazione riuscita.
**Per eliminare una CloudFormation pila**
+ Usa il seguente comando per eliminare le tue CloudFormation risorse.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## CloudFormation Modello di trasformazione dei dati completato
L'esempio seguente è un CloudFormation modello completo, che crea un'API e una tabella DynamoDB con `/pets` una risorsa `GET` con metodi and. `POST`
+ Il metodo `GET` recupererà i dati dall'endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. I dati di output verranno trasformati in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md).
+ Il metodo `POST` consentirà all'utente di pubblicare (`POST`) le informazioni sugli animali domestici in una tabella DynamoDB utilizzando un modello di mappatura.
### Modello di esempio CloudFormation
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# Esempi di utilizzo di variabili per trasformazioni dei modelli di mappatura per Gateway API
L’esempio seguente mostra come utilizzare le variabili `$context`, `input` e `util` nei modelli di mappatura. È possibile utilizzare un’integrazione fittizia o un’integrazione non proxy Lambda che restituisce l’evento di input a Gateway API. Per l’elenco di tutte le variabili supportate per le trasformazioni dei dati, consultare [Variabili per le trasformazioni dei dati per Gateway API](api-gateway-mapping-template-reference.md).
## Esempio 1: passare più variabili `$context` all’endpoint di integrazione
L'esempio seguente mostra un modello di mappatura che mappa variabili `$context` in ingresso a variabili back-end con nomi leggermente diversi nel payload di una richiesta di integrazione:
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
L'output di questo modello di mappatura deve essere analogo al seguente:
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
Una delle variabili è una chiave API. L'esempio presuppone che il metodo richieda una chiave API.
## Esempio 2: passare tutti i parametri della richiesta all’endpoint di integrazione tramite un payload JSON
L’esempio seguente passa tutti i parametri della richiesta, inclusi `path`, `querystring` e `header`, all’endpoint di integrazione tramite un payload JSON:
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
Se una richiesta ha i seguenti parametri di input:
+ Un parametro di percorso denominato `myparam`
+ Parametri della stringa di query `querystring1=value1,value2`
+ Intestazioni `"header1" : "value1"`.
L'output di questo modello di mappatura deve essere analogo al seguente:
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## Esempio 3: passare una sezione secondaria di una richiesta di metodo all’endpoint di integrazione
L’esempio seguente utilizza il parametro di input `name` per recuperare solo il parametro `name` e il parametro di input `input.json('$')` per recuperare l’intero corpo della richiesta di metodo:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
Per una richiesta che include i parametri della stringa di query `name=Bella&type=dog` e il corpo seguente:
```
{
"Price" : "249.99",
"Age": "6"
}
```
L'output di questo modello di mappatura deve essere analogo al seguente:
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
Questo modello di mappatura rimuove il parametro della stringa di query `type=dog`.
Se l'input JSON contiene caratteri senza escape che non possono essere analizzati, API JavaScript Gateway potrebbe restituire una risposta 400. Applica `$util.escapeJavaScript($input.json('$'))` per assicurare che l'input JSON possa essere analizzato correttamente.
L'esempio precedente con `$util.escapeJavaScript($input.json('$'))` applicato risulta come segue:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
In questo caso, l'output di questo modello di mappatura deve essere analogo al seguente:
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## Esempio 4: usa l' JSONPath espressione per passare una sottosezione di una richiesta di metodo all'endpoint di integrazione
L'esempio seguente utilizza le JSONPath espressioni per recuperare solo il parametro di input `name` e il testo `Age` dal corpo della richiesta:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
Per una richiesta che include i parametri della stringa di query `name=Bella&type=dog` e il corpo seguente:
```
{
"Price" : "249.99",
"Age": "6"
}
```
L'output di questo modello di mappatura deve essere analogo al seguente:
```
{
"name" : "Bella",
"body" : "6"
}
```
Questo modello di mappatura rimuove il parametro della stringa di query `type=dog` e il campo `Price` dal corpo.
Se il payload di una richiesta di metodo contiene caratteri senza escape che non possono essere analizzati, API JavaScript Gateway potrebbe restituire una risposta. `400` Applica `$util.escapeJavaScript()` per assicurare che l'input JSON possa essere analizzato correttamente.
L'esempio precedente con `$util.escapeJavaScript($input.json('$.Age'))` applicato risulta come segue:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
In questo caso, l'output di questo modello di mappatura deve essere analogo al seguente:
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## Esempio 5: utilizzare un' JSONPath espressione per passare informazioni su una richiesta di metodo all'endpoint di integrazione
L’esempio seguente utilizza `$input.params()`, `$input.path()` e `$input.json()` per inviare informazioni su una richiesta di metodo all’endpoint di integrazione. Questo modello di mappatura utilizza il metodo `size()` per fornire il numero di elementi di un elenco.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
Per una richiesta che include il parametro di percorso `123` e il corpo seguente:
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
L'output di questo modello di mappatura deve essere analogo al seguente:
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
Se il payload di una richiesta di metodo contiene caratteri senza escape che non possono essere analizzati, API JavaScript Gateway potrebbe restituire una risposta. `400` Applica `$util.escapeJavaScript()` per assicurare che l'input JSON possa essere analizzato correttamente.
L'esempio precedente con `$util.escapeJavaScript($input.json('$.things'))` applicato risulta come segue:
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
L'output di questo modello di mappatura deve essere analogo al seguente:
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# Variabili per le trasformazioni dei dati per Gateway API
Quando si crea una mappatura dei parametri, è possibile utilizzare le variabili di contesto come origine dati. Per creare le trasformazioni di modelli di mappatura, è possibile utilizzare variabili di contesto, input e util negli script scritti in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Per modelli di mappatura di esempio che utilizzano queste variabili di riferimento, consultare [Esempi di utilizzo di variabili per trasformazioni dei modelli di mappatura per Gateway API](api-gateway-mapping-variable-examples.md).
Per l’elenco delle variabili di riferimento per la registrazione degli accessi, consultare [Variabili per la registrazione dei log degli accessi per Gateway API](api-gateway-variables-for-access-logging.md).
## Variabili di contesto per le trasformazioni dei dati
È possibile utilizzare le seguenti variabili `$context` con distinzione tra maiuscole e minuscole per le trasformazioni dei dati.
| Parametro | Description |
| --- | --- |
| \$1context.accountId | L'ID dell' AWS account del proprietario dell'API. |
| \$1context.apiId | Identificatore assegnato da API Gateway all'API. |
| \$1context.authorizer.claims.property | Proprietà delle richieste restituite dal pool di utenti di Amazon Cognito dopo che l'intermediario del metodo viene autenticato correttamente. Per ulteriori informazioni, consulta [Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore](apigateway-integrate-with-cognito.md). La chiamata di `$context.authorizer.claims` restituisce null. |
| \$1context.authorizer.principalId | Identificazione dell'utente dell'entità principale associata al token inviata dal client e restituita da un'autorizzazione Lambda in API Gateway (precedentemente noto come autorizzazione ad hoc). Per ulteriori informazioni, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.property | Valore in formato stringa della coppia chiave/valore specificata della mappa `context` restituita da una funzione delle autorizzazioni Lambda di API Gateway. Ad esempio, se le autorizzazioni restituiscono la mappa `context` seguente: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} La chiamata di `$context.authorizer.key` restituisce la stringa `"value"`, la chiamata di `$context.authorizer.numKey` restituisce la stringa `"1"` e la chiamata di `$context.authorizer.boolKey` restituisce la stringa `"true"`. Infatti*property*, l'unico carattere speciale supportato è il carattere di sottolineatura`(_)`. Per ulteriori informazioni, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.awsEndpointRequestId | L'ID della richiesta dell' AWS endpoint. |
| \$1context.deploymentId | ID dell'implementazione API. |
| \$1context.domainName | Nome di dominio completo usato per richiamare l'API. Deve essere lo stesso dell'intestazione `Host` in ingresso. |
| \$1context.domainPrefix | Prima etichetta di `$context.domainName`. |
| \$1context.error.message | Stringa contenente un messaggio di errore di API Gateway. Questa variabile può essere utilizzata solo per la semplice sostituzione di variabili in un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)body mapping, che non viene elaborato dal motore Velocity Template Language, e nella registrazione degli accessi. Per ulteriori informazioni, consultare [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md) e [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | Valore \$1context.error.message tra virgolette, ovvero "\$1context.error.message". |
| \$1context.error.responseType | [Un tipo di. [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) Questa variabile può essere utilizzata solo per la semplice sostituzione di variabili in un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)body mapping, che non viene elaborato dal motore Velocity Template Language, e nella registrazione degli accessi. Per ulteriori informazioni, consultare [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md) e [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Stringa contenente un messaggio dettagliato di errore di convalida. |
| \$1context.extendedRequestId | ID esteso generato da API Gateway e assegnato alla richiesta API. L’ID della richiesta esteso contiene ulteriori informazioni utili per il debug e la risoluzione dei problemi. |
| \$1context.httpMethod | Metodo HTTP usato. I valori validi sono: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. |
| \$1context.identity.accountId | L'ID dell'account associato alla richiesta. AWS |
| \$1context.identity.apiKey | Per i metodi API che richiedono una chiave API, questa variabile è la chiave API associata alla richiesta del metodo. Per i metodi che non richiedono una chiave API, questa variabile è null. Per ulteriori informazioni, consulta [Piani di utilizzo e chiavi API per REST APIs in API Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | ID chiave API associato a una richiesta API che richiede una chiave API. |
| \$1context.identity.caller | Identificatore dell'entità principale dell'intermediario che ha firmato la richiesta. Supportato per risorse che utilizzano l'autorizzazione IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Un elenco separato da virgole con tutti i provider di autenticazione Amazon Cognito utilizzati dal chiamante che effettua la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. Ad esempio, per un'identità di un pool di utenti Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Per informazioni sui provider di autenticazione Amazon Cognito disponibili, consulta [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) nella *Guida per gli sviluppatori di Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | Tipo di autenticazione Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. I valori possibili includono `authenticated` per le identità autenticate e `unauthenticated` per le identità non autenticate. |
| \$1context.identity.cognitoIdentityId | ID identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID pool di identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. |
| \$1context.identity.principalOrgId | L'[ID organizzazione AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta all'endpoint di Gateway API. |
| \$1context.identity.clientCert.clientCertPem | Certificato client codificato PEM che il client ha presentato durante l'autenticazione TLS reciproca. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. |
| \$1context.identity.clientCert.subjectDN | Nome distinto dell'oggetto del certificato presentato da un client. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. |
| \$1context.identity.clientCert.issuerDN | Nome distinto dell'approvatore del certificato presentato da un cliente. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. |
| \$1context.identity.clientCert.serialNumber | Il numero di serie del certificato. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. |
| \$1context.identity.clientCert.validity.notBefore | La data prima della quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. |
| \$1context.identity.clientCert.validity.notAfter | La data dopo la quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. |
| \$1context.identity.vpcId | L'ID VPC del VPC da cui proviene la richiesta all'endpoint Gateway API. |
| \$1context.identity.vpceId | L'ID endpoint VPC dell'endpoint VPC da cui proviene la richiesta all'endpoint Gateway API. Presente solo quando si dispone di un'API privata. |
| \$1context.identity.user | Identificatore dell'entità principale dell'utente che sarà autorizzato per l'accesso alle risorse. Supportato per risorse che utilizzano l'autorizzazione IAM. |
| \$1context.identity.userAgent | Intestazione [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) del chiamante API. |
| \$1context.identity.userArn | Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. Per ulteriori informazioni, consulta [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.isCanaryRequest | Restituisce `true` se la richiesta era indirizzata al canary e `false` se la richiesta non era indirizzata al canary. Presente solo quando è abilitato un canary. |
| \$1context.path | Percorso della richiesta. Ad esempio, per un URL di richiesta non proxy https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, il valore di \$1context.path è /\$1stage\$1/root/child. |
| \$1context.protocol | Protocollo della richiesta, ad esempi, HTTP/1.1. API Gateway APIs può accettare richieste HTTP/2, ma API Gateway invia richieste alle integrazioni di backend utilizzando HTTP/1.1. Di conseguenza, il protocollo di richiesta viene registrato come HTTP/1.1 anche se un client invia una richiesta che utilizza HTTP/2. |
| \$1context.requestId | L'ID della richiesta. I client possono sovrascrivere questo ID di richiesta. Utilizza `$context.extendedRequestId` per un ID di richiesta univoco generato da API Gateway. |
| \$1context.requestOverride.header.header\$1name | Sovrascrittura intestazione della richiesta. Se definito, questo parametro contiene le intestazioni da utilizzare al posto delle **intestazioni HTTP** che sono definite nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | Sovrascrittura percorso della richiesta. Se definito, questo parametro contiene il percorso della richiesta da utilizzare al posto dei **parametri di percorso URL** che sono definiti nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | Sovrascrittura stringa di query della richiesta. Se definito, questo parametro contiene la stringa di query della richiesta da utilizzare al posto dei **URL Query String Parameters (Parametri stringa di query URL)** che sono definiti nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.header.header\$1name | Sovrascrittura intestazione della risposta. Se definito, questo parametro contiene l'intestazione da restituire al posto della Response header (Intestazione di risposta) che è definita come la Default mapping (mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | Sovrascrittura codice di stato della risposta. Se definito, questo parametro contiene il codice di stato da restituire al posto di Method response status (Stato risposta metodo) che è definito come la Default mapping (Mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestTime | Ora della richiesta in formato [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | L'ora della richiesta in formato [epoca (Unix epoch)](https://en.wikipedia.org/wiki/Unix_time) in millisecondi. |
| \$1context.resourceId | Identificatore assegnato da API Gateway alla risorsa. |
| \$1context.resourcePath | Percorso della risorsa. Ad esempio, per l'URI della richiesta non proxy di `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, il valore di `$context.resourcePath` è `/root/child`. Per ulteriori informazioni, consulta [Tutorial: creazione di una REST API con un'integrazione non proxy HTTP](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | La fase di distribuzione della richiesta API (ad esempio `Beta` o `Prod`). |
| \$1context.wafResponseCode | La risposta ricevuta da [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` o `WAF_BLOCK`. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta [Utilizzalo AWS WAF per proteggere il tuo REST APIs in API Gateway](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | ARN completo della lista di controllo accessi Web usata per stabilire se consentire o bloccare la richiesta. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta [Utilizzalo AWS WAF per proteggere il tuo REST APIs in API Gateway](apigateway-control-access-aws-waf.md). |
## Variabili input
È possibile utilizzare le seguenti variabili `$input` con distinzione tra maiuscole e minuscole per fare riferimento ai parametri e al payload della richiesta di metodo. Sono disponibili le funzioni seguenti:
| Variabile e funzione | Descrizione |
| --- | --- |
| \$1input.body | Restituisce il payload della richiesta non elaborata come stringa. È possibile utilizzare `$input.body` per conservare interi numeri in virgola mobile, ad esempio `10.00`. |
| \$1input.json(x) | Questa funzione valuta un' JSONPath espressione e restituisce i risultati come stringa JSON. Ad esempio, `$input.json('$.pets')` restituisce una stringa JSON che rappresenta la struttura `pets`. Per ulteriori informazioni su JSONPath, vedere [JSONPath](https://goessner.net/articles/JsonPath/)or [JSONPath for](https://github.com/json-path/JsonPath) Java. |
| \$1input.params() | Restituisce una mappa di tutti i parametri della richiesta. Si consiglia di utilizzare `$util.escapeJavaScript` per sanificare il risultato ed evitare un potenziale attacco di iniezione. Per il pieno controllo della sanificazione delle richieste, utilizzare un'integrazione proxy senza un modello e gestire la sanificazione delle richieste nell'integrazione. |
| \$1input.params(x) | Restituisce il valore di un parametro della richiesta del metodo dal percorso, dalla stringa di query o dal valore dell'intestazione (cercati in questo ordine) a partire da una stringa del nome del parametro `x`. Si consiglia di utilizzare `$util.escapeJavaScript` per sanificare il parametro ed evitare un potenziale attacco di iniezione. Per il controllo completo della sanificazione dei parametri, utilizzare un'integrazione proxy senza un modello e gestire la sanificazione delle richieste nell'integrazione. |
| \$1input.path(x) | Accetta una stringa di JSONPath espressione (`x`) e restituisce una rappresentazione in oggetto JSON del risultato. In questo modo, puoi accedere agli elementi del payload e modificarli in modo nativo in [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Ad esempio, se l'espressione `$input.path('$.pets')` restituisce un oggetto in questo modo: [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()` restituisce `"3"`. Per ulteriori informazioni su JSONPath, vedere [JSONPath](https://goessner.net/articles/JsonPath/)or [JSONPath for Java](https://github.com/json-path/JsonPath). |
## Variabili di fase
È possibile utilizzare le seguenti variabili di fase come segnaposto per ARNs e URLs nelle integrazioni di metodi. Per ulteriori informazioni, consulta [Utilizzo delle variabili di fase per una REST API in Gateway API](stage-variables.md).
| Sintassi | Description |
| --- | --- |
| \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'] o \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*rappresenta il nome di una variabile di fase. |
## Variabili util
È possibile utilizzare le seguenti variabili `$util` con distinzione tra maiuscole e minuscole per usare le funzioni di utilità per i modelli di mappatura. Se non diversamente specificato, il set di caratteri predefinito è UTF-8.
| Funzione | Description |
| --- | --- |
| \$1util.escapeJavaScript() | Sfugge ai caratteri di una stringa utilizzando le regole delle JavaScript stringhe. Questa funzione trasforma qualsiasi virgoletta singola (`'`) in virgoletta preceduta da un carattere escape (`\'`). Tuttavia, le virgolette singole con escape non sono valide in JSON. Di conseguenza, quando l'output di questa funzione viene usato in una proprietà JSON, devi modificare di nuovo qualsiasi virgoletta singola con carattere escape (`\'`) in virgoletta singola normale (`'`). Questo viene mostrato nell'esempio seguente: "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | Da una stringa JSON restituisce una rappresentazione oggetto del risultato. Puoi usare il risultato di questa funzione per accedere agli elementi del payload e modificarli in modo nativo in Apache Velocity Template Language (VTL). Ad esempio, in presenza del payload seguente: {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} E se usi il modello di mappatura seguente: #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Otterrai l'output seguente: {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Converte una stringa nel formato «application/x-www-form-urlencoded». |
| \$1util.urlDecode() | Decodifica una stringa «application/». x-www-form-urlencoded |
| \$1util.base64Encode() | Codifica i dati in una stringa con codifica base64. |
| \$1util.base64Decode() | Decodifica i dati da una stringa con codifica base64. |