Invocazione dell'integrazione backend con l'instradamento $default e gli instradamenti personalizzati in Gateway API
La sezione seguente descrive come invocare l'integrazione backend utilizzando l'instradamento $default o un instradamento personalizzato per un'API WebSocket.
Argomenti
Utilizzo di instradamenti per elaborare messaggi
Nelle API WebSocket API Gateway, i messaggi possono essere inviati dal client al servizio di back-end e viceversa. A differenza del modello di richiesta/risposta di HTTP, in WebSocket il back-end può inviare messaggi al client senza che questo esegua alcuna operazione.
I messaggi possono essere JSON o non JSON. Tuttavia, solo i messaggi JSON possono essere instradati a integrazioni specifiche in base al contenuto del messaggio. I messaggi non JSON vengono trasmessi al back-end dalla route $default.
Nota
API Gateway supporta payload dei messaggi fino a 128 KB con dimensione del frame massima di 32 KB. Se un messaggio supera i 32 KB, occorre suddividerlo in più frame, ciascuno di 32 KB o più piccolo. Se si riceve un messaggio (o frame) di dimensioni maggiori, la connessione viene chiusa con codice 1009.
Al momento i payload binari non sono supportati. Se si riceve un frame binario, la connessione viene chiusa con codice 1003. Tuttavia, è possibile convertire i payload binari in testo. Consulta Tipi di supporti binari per API WebSocket in Gateway API.
Con le API WebSocket in API Gateway, i messaggi JSON possono essere instradati per eseguire un servizio di back-end specificato in base al contenuto del messaggio. Quando un client invia un messaggio sulla sua connessione WebSocket, questo genera una richiesta di instradamento all'API WebSocket. La richiesta verrà associata alla route con la chiave route corrispondente in API Gateway. Puoi impostare una richiesta di routing per un'API WebSocket nella console API Gateway utilizzando la AWS CLI o un SDK AWS.
Nota
Nei kit SDK AWS CLI e AWS, è possibile creare instradamenti prima o dopo aver creato l'integrazione. Attualmente la console non supporta il riutilizzo di integrazioni, perciò è necessario creare la route prima e quindi creare l'integrazione per tale route.
Puoi configurare API Gateway per eseguire la convalida su una route prima di passare alla richiesta di integrazione. Se la convalida ha esito negativo, API Gateway rifiuta la richiesta senza chiamare il back-end, invia una risposta del gateway "Bad request body" simile alla seguente al client e pubblica i risultati di convalida in CloudWatch Logs:
{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}
Ciò consente di ridurre le chiamate non necessarie al back-end e concentrarsi sugli altri requisiti dell'API.
Puoi anche definire una risposta di instradamento per le route dell'API per abilitare la comunicazione bidirezionale. Una risposta di instradamento descrive quali dati verranno inviati al client al termine dell'integrazione di una particolare route. Non è necessario definire una risposta per una route se, ad esempio, desideri che un client invii messaggi al back-end senza ricevere una risposta (comunicazione unidirezionale). Tuttavia, se non fornisci una risposta di instradamento, API Gateway non invierà informazioni sul risultato dell'integrazione ai client.
Instradamento $default
Ogni API WebSocket API Gateway può avere una route $default. Si tratta di un valore di instradamento speciale che può essere utilizzato nei seguenti modi:
-
Puoi usarlo insieme a chiavi di route definite per specificare una route di "fallback", ad esempio un'integrazione fittizia generica che restituisce un determinato messaggio di errore, per i messaggi in ingresso che non corrispondono ad alcuna delle chiavi di route definite.
-
Puoi utilizzarlo senza alcuna chiave route definita, per specificare un modello di proxy che delega l'instradamento a un componente di back-end.
-
Puoi utilizzarlo per specificare una route per payload non JSON.
Instradamenti personalizzati
Se desideri invocare un'integrazione specifica in base al contenuto del messaggio, puoi farlo creando una route personalizzata.
Una route personalizzata utilizza una chiave route e l'integrazione specificati dall'utente. Quando un messaggio in entrata contiene una proprietà JSON e tale proprietà valuta un valore che corrisponde al valore della chiave route, API Gateway richiama l'integrazione. (Per ulteriori informazioni, consulta Panoramica delle API WebSocket in Gateway API.)
Ad esempio, supponiamo che tu voglia creare un'applicazione chat room. Potresti iniziare creando un'API WebSocket la cui espressione di selezione della route è $request.body.action. Potresti quindi definire due route: joinroom e sendmessage. Un'app client potrebbe richiamare la route joinroom inviando un messaggio del tipo seguente:
{"action":"joinroom","roomname":"developers"}
E potrebbe richiamare la route sendmessage inviando un messaggio del tipo seguente:
{"action":"sendmessage","message":"Hello everyone"}
Utilizzo delle integrazioni API WebSocket API Gateway per la connessione alla logica di business
Dopo aver configurato una route per un'API WebSocket API Gateway, devi specificare l'integrazione che desideri utilizzare. Come nel caso di una route, per la quale è possibile avere una richiesta di instradamento e una risposta di instradamento, un'integrazione può avere una richiesta di integrazione e una risposta di integrazione. Una richiesta di integrazione contiene le informazioni previste dal back-end per elaborare la richiesta proveniente dal client. Una risposta di integrazione contiene i dati restituiti dal back-end ad API Gateway e che possono essere utilizzati per costruire un messaggio da inviare al cliente (se è definita una risposta di instradamento).
Per ulteriori informazioni sulla configurazione di integrazioni, consulta Integrazioni per API WebSocket in Gateway API.
Differenze importanti tra API WebSocket e API REST
Le integrazione per API WebSocket sono simili alle integrazioni per API REST, ad eccezione delle seguenti differenze:
-
Al momento, nella console API Gateway è necessario creare prima una route e quindi un'integrazione come destinazione di tale route. Tuttavia, nell'API e nella CLI, puoi creare route e integrazioni in modo indipendente, in qualsiasi ordine.
-
Puoi utilizzare una singola integrazione per più route. Ad esempio, se disponi di un set di operazioni tra loro strettamente correlate, puoi fare in modo che tutte queste route vadano in una singola funzione Lambda. Anziché definire più volte i dettagli dell'integrazione, puoi specificarla una sola volta e assegnarla a ciascuna delle route correlate.
Nota
Attualmente la console non supporta il riutilizzo di integrazioni, perciò è necessario creare la route prima e quindi creare l'integrazione per tale route.
Negli SDK AWS CLI e AWS , puoi riutilizzare un'integrazione impostando la destinazione dell’instradamento su un valore di
"integrations/, in cui{integration-id}"{integration-id}" -
API Gateway fornisce più espressioni di selezione che puoi utilizzare nelle route e nelle integrazioni. Non è necessario basarsi sul tipo di contenuto per selezionare un modello di input o una mappatura di output. Analogamente alle espressioni di selezione della route, puoi definire un'espressione di selezione che deve essere valutata da API Gateway per scegliere l'elemento corretto. Tutte verranno ripristinati al modello
$defaultse non viene trovato un modello corrispondente.-
Nelle richieste di integrazione, l'espressione di selezione del modello supporta
$request.body.e valori statici.<json_path_expression> -
Nelle risposte di integrazione, l'espressione di selezione del modello supporta
$request.body.,<json_path_expression>$integration.response.statuscode,$integration.response.header.e valori statici.<headerName>
-
Nel protocollo HTTP, in cui richieste e risposte vengono inviate in maniera sincrona, la comunicazione è essenzialmente unidirezionale. Nel protocollo WebSocket, la comunicazione è bidirezionale. Le risposte sono asincrone e non vengono necessariamente ricevute dal client nello stesso ordine di invio dei messaggi del client. Inoltre, il back-end può inviare messaggi al client.
Nota
Per una route configurata per utilizzare l'integrazione AWS_PROXY o LAMBDA_PROXY, la comunicazione è unidirezionale e API Gateway non trasferisce automaticamente la risposta del back-end alla risposta di instradamento. Ad esempio, in caso dell'integrazione LAMBDA_PROXY, il corpo restituito dalla funzione Lambda non verrà restituito al client. Se desideri che il client riceva risposte di integrazione, devi definire una risposta di instradamento per rendere possibile la comunicazione bidirezionale.
