Trasforma API le richieste e le risposte per HTTP APIs in API Gateway - Amazon API Gateway
Trasformazione delle richieste APITrasformare le risposte APIIntestazioni riservateEsempi

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

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

Puoi modificare le API richieste dei clienti prima che raggiungano le tue integrazioni di backend. Puoi anche modificare la risposta delle integrazioni prima che API Gateway restituisca la risposta ai client. Si utilizza la mappatura dei parametri per modificare le API richieste e le risposte per. HTTP APIs Per utilizzare la mappatura dei parametri, è necessario specificare i parametri di API richiesta o risposta da modificare e specificare come 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.

Type 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.

Type Sintassi Note
Valore intestazione $request.header.name o $ {request.header.name} I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. APIAd esempio, Gateway combina più valori di intestazione con virgole. "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. APIAd esempio, Gateway combina più valori con virgole. "querystring1" "Value1,Value2"
Corpo della richiesta $request.body.name o $ {request.body.name} Un'espressione di JSON percorso. Le espressioni di discesa ricorsiva ($request.body..name)) e di filtro (?(expression)) non sono supportate.
Nota

Quando si specifica un JSON percorso, 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 $contesto.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 string 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}.

Trasformare le risposte API

Si utilizzano i parametri di risposta per trasformare la HTTP risposta da un'integrazione di backend prima di restituire la risposta ai client. È possibile modificare le intestazioni o il codice di stato di una risposta prima che API Gateway 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.

Type 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.

Type Sintassi Note
Valore intestazione $response.header.name o $ {response.header.name} I nomi delle intestazioni non fanno distinzione tra maiuscole e minuscole. APIAd esempio, Gateway combina più valori di intestazione con virgole. "header1": "value1,value2" Alcune intestazioni sono riservate. Per ulteriori informazioni, consulta Intestazioni riservate.
Corpo di risposta $response.body.name o $ {response.body.name} Un'JSONespressione di percorso. Le espressioni di discesa ricorsiva ($response.body..name) e di filtro (?(expression)) non sono supportate.
Nota

Quando si specifica un JSON percorso, 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 $contesto.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 string 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

L'esempio seguente aggiunge un'intestazione denominata header1 a una API richiesta prima che raggiunga l'integrazione del backend. APIGateway compila l'intestazione con l'ID della 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 header1 1 alla risposta. Quando l'integrazione restituisce un codice di stato 404, API Gateway aggiunge un'errorintestazione 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" : {}}'