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

Questa sezione spiega come impostare le mappature dei dati dai dati API di una richiesta di metodo, inclusi altri dati archiviati in context, o utilvariabili stage, ai parametri di richiesta di integrazione corrispondenti e dai dati di risposta di integrazione, inclusi gli altri dati, ai parametri di risposta del 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 APIRiferimento alle variabili di fase Gateway per REST APIs in Gateway API.

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 di un parametro di richiesta del metodo del tipo di parametro specificato. Deve corrispondere all'espressione regolare '^[a-zA-Z0-9._$-]+$]'. Deve essere stato definito prima che possa essere referenziato. JSONPath_EXPRESSION è un'JSONPathespressione per un JSON campo del corpo di una richiesta o di una risposta.

...
"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 del corpo della JSON richiesta utilizzando un'espressione. JSONPath La tabella seguente mostra le espressioni di mappatura per un corpo di richiesta del metodo e i relativi JSON campi.

...
"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. La tabella seguente descrive le espressioni di mappatura dell'intestazione della risposta del 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

APIGateway utilizza il motore Velocity Template Language (VTL) per elaborare i modelli di body mapping per la richiesta di integrazione 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 VTL modelli utilizzano JSONPath espressioni, altri parametri come contesti di chiamata e variabili di fase e funzioni di utilità per elaborare i dati. JSON

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

Seleziona un modello di mappatura VTL

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

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

Quando l'Content-Typeintestazione è assente nella richiesta, API Gateway presume 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. Quando nessun modello corrisponde a questa chiave, API Gateway passa il payload a unmapped se la passthroughBehaviorproprietà è impostata su o. WHEN_NO_MATCH WHEN_NO_TEMPLATES

Quando l'Acceptintestazione non è specificata nella richiesta, API Gateway presume che il suo valore predefinito sia. application/json In questo caso, API Gateway seleziona un modello di mappatura esistente per mappare il payload application/json di risposta. Se non è definito alcun modello perapplication/json, API Gateway seleziona il primo modello esistente e lo utilizza come predefinito per mappare il payload di risposta. Analogamente, API Gateway utilizza il primo modello esistente quando il valore di Accept intestazione specificato non corrisponde a nessuna chiave del modello esistente. Se non viene definito alcun modello, API Gateway passa semplicemente il payload di risposta tramite unmapped.

Ad esempio, supponiamo che un API abbia un application/json modello definito per un payload di richiesta e abbia un application/xml modello definito per il payload di 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.

Quando si seleziona un modello di mappatura, viene utilizzato solo il MIME tipo Content-Type contenuto nelle intestazioni Accept and. Ad esempio, un'intestazione di "Content-Type: application/json; charset=UTF-8" avrà un modello di richiesta con la chiave application/json selezionata.