Trasformazioni dei dati per REST API in Gateway API
Nota
In questa sezione vengono illustrate le funzionalità da utilizzare con un’integrazione non proxy. Tuttavia, è consigliabile, ove possibile, usare un’integrazione proxy per la REST API. L’integrazione proxy ha una configurazione di integrazione più semplice e può evolvere con il backend senza annullare le impostazioni esistenti. Per ulteriori informazioni, consultare Scegliere un tipo di integrazione API Gateway API.
Se si utilizza un’integrazione non proxy, è possibile usare due funzionalità di Gateway API per trasformare la richiesta di metodo e la risposta di integrazione. È possibile trasformare la richiesta di metodo se utilizza un formato di payload diverso rispetto al payload della richiesta di integrazione. È possibile trasformare la risposta di integrazione se restituisce un formato di payload diverso da quello che deve essere restituito nella risposta di metodo. Per ulteriori informazioni sul ciclo di vita della richiesta, consultare Risorsa di esempio per una REST API.
L’esempio seguente mostra una trasformazione di dati in cui per l’intestazione "x-version:beta", il parametro di intestazione x-version viene trasformato nel parametro di intestazione app-version. La trasformazione di dati da x-version a app-version avviene nella richiesta di integrazione. In questo modo, l’endpoint di integrazione riceve il valore del parametro di intestazione trasformato. Quando l’endpoint di integrazione restituisce un codice di stato, il codice di stato viene trasformato da 200 a 204 prima della risposta di metodo.
Per creare una trasformazione di dati, è possibile utilizzare le seguenti funzionalità:
- Mappatura dei parametri
-
Nella mappatura dei parametri, è possibile modificare i parametri del percorso URL della richiesta di integrazione, i parametri della stringa di query URL o i valori dell’intestazione HTTP, ma non è possibile modificare il payload della richiesta di integrazione. È inoltre possibile modificare i valori dell’intestazione della risposta HTTP. La mappatura dei parametri si utilizza per creare valori di intestazione statici per CORS (Cross-Origin Resource Sharing).
È possibile utilizzare la mappatura dei parametri nella richiesta di integrazione per integrazioni proxy e non proxy, ma per usarla per una risposta di integrazione, è necessaria un’integrazione non proxy. La mappatura dei parametri non richiede script in Velocity Template Language (VTL)
. Per ulteriori informazioni, consultare Mappatura dei parametri per REST API in Gateway API. - Trasformazioni dei modelli di mappatura
-
Nelle trasformazioni dei modelli di mappatura, si usa un modello di mappatura per mappare i parametri del percorso URL, i parametri della stringa di query URL, le intestazioni HTTP e la richiesta di integrazione o il corpo della risposta di integrazione. Un modello di mappatura è uno script espresso in Velocity Template Language (VTL)
utilizzando espressioni JSONPath e applicato al payload in base all’intestazione Content-type.Con un modello di mappatura è possibile eseguire le seguenti operazioni:
-
Selezionare i dati da inviare utilizzando l'integrazione conServizi AWS, ad esempio le funzioni Amazon DynamoDB o Lambda o gli endpoint HTTP. Per ulteriori informazioni, consultare Tutorial: modificare la richiesta e la risposta di integrazione per le integrazioni ai servizi AWS.
-
Sostituire in modo condizionale i parametri di richiesta e risposta di integrazione di un’API, creare nuovi valori di intestazione e sostituire i codici di stato. Per ulteriori informazioni, consultare Sostituzione dei parametri della richiesta e della risposta e dei codici di stato per REST API in Gateway API.
È anche possibile specificare il comportamento dell’API quando il corpo di una richiesta di integrazione ha un’intestazione
Content-typesenza modelli di mappatura corrispondenti. Questo processo è chiamato comportamento passthrough di integrazione. Per ulteriori informazioni, consultare Comportamento della richiesta di metodo per i payload senza modelli di mappatura per REST API in Gateway API. -
Scelta tra mappatura dei parametri e trasformazioni dei modelli di mappatura
Quando possibile, è consigliabile utilizzare la mappatura dei parametri per trasformare i dati. Se l’API richiede la modifica del corpo o l’esecuzione di sostituzioni e modifiche condizionali in base alla richiesta o alla risposta di integrazione in entrata e non è possibile utilizzare un’integrazione proxy, si usano le trasformazioni dei modelli di mappatura.
