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à.
# 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).