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 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\":{}}"}
```