Riferimento alla mappatura dei dati di richiesta e di risposta delle API di Amazon API Gateway

Questa sezione spiega come impostare le mappature dei dati dai dati della richiesta di metodo dell'API, inclusi altri dati archiviati nelle variabili context, stage o util, ai parametri della richiesta di integrazione corrispondenti e dai dati della risposta di integrazione, inclusi altri dati, ai parametri della risposta di metodo. I dati della richiesta del metodo includono i parametri di richiesta (percorso, stringa di query, intestazioni) e il corpo. I dati della risposta di integrazione includono i parametri di risposta (intestazioni) e il corpo. Per ulteriori informazioni sull'uso delle variabili di fase, consulta Riferimento alle variabili di fase di API Gateway.

Argomenti

• Come mappare i dati di richiesta di metodi ai parametri di richiesta di integrazione
• Mappa i dati delle risposte di integrazione alle intestazioni delle risposte di metodo
• Mappa i payload di risposta e di richiesta tra metodo e integrazione
• Comportamenti passthrough di integrazione

Come mappare i dati di richiesta di metodi ai parametri di richiesta di integrazione

I parametri di richiesta di integrazione, sotto forma di variabili di percorso, stringhe o intestazioni di query, possono essere mappati dal payload e da qualsiasi parametro di richiesta di metodo definito.

Nella tabella seguente, PARAM_NAME è il nome del parametro della richiesta di metodo del tipo di parametro considerato. Deve corrispondere all'espressione regolare '^[a-zA-Z0-9._$-]+$]'. Prima di fare riferimento al parametro, è necessario definirlo. JSONPath_EXPRESSION è un'espressione JSONPath di un campo JSON del corpo di una richiesta o di una risposta.

Nota

Il prefisso "$" viene omesso in questa sintassi.

Espressioni di mappatura dei dati di richieste di integrazione
Origine dati mappata	Espressione di mappatura
Percorso della richiesta di metodo	method.request.path.PARAM_NAME
Stringa di query della richiesta di metodo	method.request.querystring.PARAM_NAME
Stringa di query multi-valore della richiesta del metodo	method.request.multivaluequerystring.PARAM_NAME
Intestazione della richiesta di metodo	method.request.header.PARAM_NAME
Intestazione multi-valore della richiesta di metodo	method.request.multivalueheader.PARAM_NAME
Corpo della richiesta di metodo	method.request.body
corpo della richiesta del metodo () JsonPath	method.request.body.JSONPath_EXPRESSION.
Variabili di fase	stageVariables.VARIABLE_NAME
Variabili di contesto	context.VARIABLE_NAME che deve essere una delle variabili di contesto supportate.
Valore statico	'STATIC_VALUE'. STATIC_VALUE è una stringa letterale che deve essere racchiusa da una coppia di virgolette singole.

Esempio Mappature dal parametro di richiesta del metodo in OpenAPI

L'esempio seguente mostra un frammento OpenAPI che mappa:

• l'intestazione della richiesta del metodo, methodRequestHeaderParam, al parametro di percorso integrationPathParam della richiesta di integrazione

• la stringa di query multi-valore della richiesta del metodo, methodRequestQueryParam, alla stringa di query della richiesta di integrazione, integrationQueryParam

...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam"
            
}
...
                
            

I parametri della richiesta di integrazione possono anche essere mappati dai campi nel corpo della richiesta JSON tramite una Espressione JSONPath. La tabella seguente mostra le espressioni di mappatura per un corpo di una richiesta di metodo e i relativi campi JSON.

Esempio Mappatura dal corpo della richiesta di metodo in OpenAPI

L'esempio seguente mostra un frammento OpenAPI che mappa 1) il corpo della richiesta di metodo all'intestazione della richiesta di integrazione, denominata body-header e 2) un campo JSON del corpo, formulato da un'espressione JSON (petstore.pets[0].name, senza il prefisso $.).

...
"requestParameters" : {
            
    "integration.request.header.body-header" : "method.request.body",
    "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name",
            
}
...
                
            

Mappa i dati delle risposte di integrazione alle intestazioni delle risposte di metodo

I parametri delle intestazioni delle risposte di metodo possono essere mappati da qualsiasi intestazione o corpo della risposta di integrazione, variabili $context o valori statici.

Espressioni delle mappature delle intestazioni per le risposte di metodo
Origine dati mappata	Espressione di mappatura
Intestazione della risposta di integrazione	integration.response.header.PARAM_NAME
Intestazione della risposta di integrazione	integration.response.multivalueheader.PARAM_NAME
Corpo della risposta di integrazione	integration.response.body
Corpo della risposta di integrazione (JsonPath)	integration.response.body.JSONPath_EXPRESSION
Variabile di fase	stageVariables.VARIABLE_NAME
Variabile di contesto	context.VARIABLE_NAME che deve essere una delle variabili di contesto supportate.
Valore statico	'STATIC_VALUE'. STATIC_VALUE è una stringa letterale che deve essere racchiusa da una coppia di virgolette singole.

Esempio Mappatura dei dati dalla risposta di integrazione in OpenAPI

L'esempio seguente mostra un frammento OpenAPI che mappa 1) redirect.url della risposta di integrazione, il campo JSONPath nell'intestazione location della risposta della richiesta e 2) l'intestazione x-app-id della risposta di integrazione all'intestazione id della risposta di metodo.

...
"responseParameters" : {
            
    "method.response.header.location" : "integration.response.body.redirect.url",
    "method.response.header.id" : "integration.response.header.x-app-id",
    "method.response.header.items" : "integration.response.multivalueheader.item",
            
}
...
                
            

Mappa i payload di risposta e di richiesta tra metodo e integrazione

API Gateway utilizza il motore Velocity Template Language (VTL) per elaborare i modelli di mappatura del corpo per la richiesta e la risposta di integrazione. I modelli di mappatura traducono i payload delle richieste di metodo nei payload della richiesta di integrazione corrispondenti e i corpi delle risposte di integrazione nei corpi delle risposte di metodo corrispondenti.

I modelli VTL utilizzano le espressioni JSONPath, altri parametri come contesti di chiamata, variabili di fase e funzioni di utility per elaborare i dati JSON.

Se un modello viene definito per descrivere la struttura dati di un payload, API Gateway può utilizzare il modello per generare un modello di mappatura scheletrale per una richiesta o una risposta di integrazione. Puoi utilizzare il modello scheletrale come supporto per personalizzare ed espandere lo script VTL di mappatura. Tuttavia, puoi creare un nuovo modello di mappatura senza definire un modello per la struttura dati del payload.

Seleziona un modello di mappatura VTL

API Gateway utilizza la logica seguente per selezionare un modello di mappatura, in Velocity Template Language (VTL), per mappare il payload da una richiesta del metodo alla richiesta di integrazione corrispondente o per mappare il payload da una risposta di integrazione alla risposta del metodo corrispondente.

Per un payload della richiesta, API Gateway utilizza il valore dell'intestazione Content-Type della richiesta come chiave per selezionare il modello di mappatura per il payload di richiesta. Per un payload della risposta, API Gateway utilizza il valore dell'intestazione Accept della richiesta in entrata come chiave per selezionare il modello di mappatura.

Quando l'intestazione Content-Type non è presente nella richiesta, API Gateway presuppone che il suo valore predefinito sia application/json. Per tale richiesta, API Gateway utilizza application/json come chiave predefinita per selezionare il modello di mappatura, se definito. Se nessun modello corrisponde a questa chiave, API Gateway passa il payload non mappato se la proprietà passthroughBehavior è impostata su WHEN_NO_MATCH o WHEN_NO_TEMPLATES.

Quando l'intestazione Accept non è specificata nella richiesta, API Gateway presuppone che il valore predefinito sia application/json. In questo caso, API Gateway seleziona un modello di mappatura esistente per application/json per mappare il payload della risposta. Se nessun modello è stato definito per application/json, API Gateway seleziona il primo modello esistente e lo utilizza come predefinito per mappare il payload della risposta. Allo stesso modo, API Gateway utilizza il primo modello esistente quando il valore dell'intestazione Accept specificato non corrisponde ad alcuna chiave del modello esistente. Se nessun modello è stato definito, API Gateway semplicemente passa il payload della risposta non mappato.

Ad esempio, supponiamo che un'API abbia un modello application/json definito per il payload di una richiesta e abbia un modello application/xml definito per il payload di una risposta. Se il client imposta le intestazioni "Content-Type : application/json" e "Accept : application/xml" nella richiesta, i payload di richiesta e di risposta verranno elaborati con i modelli di mappatura corrispondenti. Se l'intestazione Accept:application/xml non è presente, verrà utilizzato il modello di mappatura application/xml per mappare il payload della risposta. Al contrario, per restituire il payload di risposta non mappato, devi configurare un modello vuoto per application/json.

Solo il tipo MIME viene utilizzato per le intestazioni Accept e Content-Type quando selezioni un modello di mappatura. Ad esempio, un'intestazione di "Content-Type: application/json; charset=UTF-8" avrà un modello di richiesta con la chiave application/json selezionata.