Trasforma le richieste e le risposte API per le API HTTP in API Gateway

È possibile modificare le richieste API dai client prima che raggiungano le integrazioni back-end. È inoltre possibile modificare la risposta dalle integrazioni prima che API Gateway restituisca la risposta ai client. È possibile utilizzare la mappatura dei parametri per modificare le richieste e le risposte API per le API HTTP. Per utilizzare la mappatura dei parametri, specificare i parametri di richiesta o risposta API da modificare e la modalità per modificare tali parametri.

Trasformazione delle richieste API

È possibile utilizzare i parametri di richiesta per modificare le richieste prima che raggiungano le integrazioni back-end. È possibile modificare le intestazioni, le stringhe di query o il percorso della richiesta.

I parametri di richiesta sono una mappa chiave-valore. La chiave identificherà la posizione del parametro di richiesta da modificare e la modalità per modificarlo. Il valore specifica i nuovi dati per il parametro.

Nella tabella seguente sono illustrate le chiavi supportate.

Chiavi di mappatura dei parametri
Tipo	Sintassi
Intestazione	append|overwrite|remove:header.headername
Stringa di query	append|overwrite|remove:querystring.querystring-name
Percorso	overwrite:path

Nella tabella seguente sono illustrati i valori supportati che è possibile mappare ai parametri.

Valori di mappatura dei parametri di richiesta
Tipo	Sintassi	Note
Valore intestazione	$request.header.name o ${request.header.name}	I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori di intestazione con virgole, ad esempio "header1": "value1,value2". Alcune intestazioni sono riservate. Per ulteriori informazioni, consulta Intestazioni riservate.
Valore della stringa di query	$request.querystring.name o ${request.querystring.name}	I nomi delle stringhe di query fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori con virgole, ad esempio "querystring1" "Value1,Value2".
Corpo della richiesta	$request.body.name o ${request.body.name}	Un'espressione di percorso JSON. Le espressioni di discesa ricorsiva ($request.body..name)) e di filtro (?(expression)) non sono supportate. Nota Quando si specifica un percorso JSON, API Gateway tronca il corpo della richiesta a 100 KB e quindi applica l'espressione di selezione. Per inviare payload superiori a 100 KB, specificare $request.body.
Percorso della richiesta	$request.path o ${request.path}	Il percorso della richiesta, senza il nome della fase.
Parametro del percorso	$request.path.name o ${request.path.name}	Il valore di un parametro del percorso nella richiesta. Ad esempio, se l'instradamento è /pets/{petId}, è possibile mappare il parametro petId della richiesta con $request.path.petId.
Variabile di contesto	$context.variableName o ${context.variableName}	Il valore di una variabile di contesto. Nota Sono supportati solo i caratteri speciali . e _.
Variabile di fase	$stageVariables.variableName o ${stageVariables.variableName}	Il valore di una variabile di fase.
Valore statico	stringa	Un valore costante.

Nota

Per utilizzare più variabili in un'espressione di selezione, racchiudere la variabile tra parentesi. Ad esempio, ${request.path.name} ${request.path.id}.

Trasformazione delle risposte API

È possibile utilizzare i parametri di risposta per trasformare la risposta HTTP da un'integrazione back-end prima di restituire la risposta ai client. È possibile modificare le intestazioni o il codice di stato di una risposta prima che Gateway API restituisca la risposta ai client.

Configurare i parametri di risposta per ogni codice di stato restituito dall'integrazione. I parametri di risposta sono una mappa chiave-valore. La chiave identificherà la posizione del parametro di richiesta da modificare e la modalità per modificarlo. Il valore specifica i nuovi dati per il parametro.

Nella tabella seguente sono illustrate le chiavi supportate.

Chiavi di mappatura dei parametri di risposta
Tipo	Sintassi
Intestazione	append|overwrite|remove:header.headername
Codice di stato	overwrite:statuscode

Nella tabella seguente sono illustrati i valori supportati che è possibile mappare ai parametri.

Valori di mappatura dei parametri di risposta
Tipo	Sintassi	Note
Valore intestazione	$response.header.name o ${response.header.name}	I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. API Gateway combina più valori di intestazione con virgole, ad esempio "header1": "value1,value2". Alcune intestazioni sono riservate. Per ulteriori informazioni, consulta Intestazioni riservate.
Corpo di risposta	$response.body.name o ${response.body.name}	Un'espressione di percorso JSON. Le espressioni di discesa ricorsiva ($response.body..name) e di filtro (?(expression)) non sono supportate. Nota Quando si specifica un percorso JSON, API Gateway tronca il corpo della risposta a 100 KB e quindi applica l'espressione di selezione. Per inviare payload superiori a 100 KB, specificare $response.body.
Variabile di contesto	$context.variableName o ${context.variableName}	Valore di una variabile di contesto supportata.
Variabile di fase	$stageVariables.variableName o ${stageVariables.variableName}	Il valore di una variabile di fase.
Valore statico	stringa	Un valore costante.

Nota

Per utilizzare più variabili in un'espressione di selezione, racchiudere la variabile tra parentesi. Ad esempio, ${request.path.name} ${request.path.id}.

Intestazioni riservate

Le intestazioni seguenti sono riservate. Per queste intestazioni, non è possibile configurare le mappature di richiesta o di risposta.

• access-control-*

• apigw-*

• Autorizzazione

• Connessione

• Content-Encoding

• Content-Length

• Content-Location

• Forwarded

• Keep-Alive

• Origin

• Proxy-Authenticate

• Proxy-Authorization

• TE

• Trailers

• Transfer-Encoding

• Upgrade

• x-amz-*

• x-amzn-*

• X-Forwarded-For

• X-Forwarded-Host

• X-Forwarded-Proto

• Via

Esempi

I seguenti AWS CLI esempi configurano le mappature dei parametri. Per esempi di AWS CloudFormation modelli, vedere. GitHub

Aggiungere un'intestazione a una richiesta API

Nell'esempio seguente viene aggiunta un'intestazione denominata header1 a una richiesta API prima che raggiunga l'integrazione del backend. API Gateway popola l'intestazione con l'ID di richiesta.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }' 

Rinominare un'intestazione di richiesta

Nell'esempio seguente, viene rinominata un'intestazione di richiesta da header1 a header2.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'

Modificare la risposta da un'integrazione

Nell'esempio seguente, vengono configurati i parametri di risposta per un'integrazione. Quando le integrazioni restituiscono un codice di stato 500, API Gateway modifica il codice di stato in 403 e aggiunge header11 alla risposta. Quando l'integrazione restituisce un codice di stato 404, API Gateway aggiunge un'intestazione error alla risposta.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'

Rimuovere le mappature dei parametri configurati

Il comando di esempio seguente rimuove i parametri di richiesta configurati in precedenza per append:header.header1. Il comando rimuove anche i parametri di risposta configurati in precedenza per un codice di stato 200.

aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'