Trasformazione delle richieste e delle risposte API per API HTTP in Gateway API - Amazon API Gateway
Trasformazione delle richieste APITrasformazione delle 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à.

Trasformazione delle richieste e delle risposte API per API HTTP in Gateway API

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

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.

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.

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.

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

Gli esempi della AWS CLI seguenti configurano le mappature dei parametri. Per modelli di esempio AWS CloudFormation, vedi GitHub.

Aggiungere un'intestazione a una richiesta API

Il comando create-integration seguente crea un’intestazione denominata header1 per 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

Il comando create-integration seguente rinomina l’intestazione di una 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

Il comando create-integration seguente configura 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 update-integration 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" : {}}'