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à.
Richiamo dell'integrazione back-end: instradamenti $default e instradamenti personalizzati
Argomenti
Utilizzo di instradamenti per elaborare messaggi
Nelle API WebSocket API Gateway, i messaggi possono essere inviati dal client al servizio di backend e viceversa. A differenza del modello di richiesta/risposta di HTTP, WebSocket nel backend è possibile inviare messaggi al client senza che il client intraprenda alcuna azione.
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 Utilizzo di tipi di supporti binari per le WebSocket API.
Con le WebSocket API in API Gateway, i messaggi JSON possono essere instradati per eseguire un servizio di backend specifico basato sul contenuto dei messaggi. Quando un client invia un messaggio tramite la sua WebSocket connessione, ciò si traduce in una richiesta di routing all'API. WebSocket La richiesta verrà associata alla route con la chiave route corrispondente in API Gateway. Puoi configurare una richiesta di routing per un' WebSocket API nella console API Gateway AWS CLI, utilizzando o utilizzando un AWS SDK.
Nota
Negli AWS SDK AWS CLI e, puoi creare percorsi prima o dopo aver creato le integrazioni. 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 fallisce, API Gateway fallisce la richiesta senza chiamare il backend, invia al client una risposta del "Bad request body" gateway simile alla seguente e pubblica i risultati della convalida in Logs: CloudWatch
{"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 un $default percorso. 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 Informazioni sulle WebSocket API in API Gateway.)
Ad esempio, supponiamo che tu voglia creare un'applicazione chat room. Potresti iniziare creando un' WebSocket API la cui espressione di selezione del percorso è$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 WebSocket API Gateway per connettersi alla logica aziendale
Dopo aver impostato un percorso 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 Configurazione delle integrazioni WebSocket API.
Differenze importanti tra WebSocket API e API REST
Le integrazioni per le WebSocket API sono simili alle integrazioni per le 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 AWS CLI and AWS SDK, puoi riutilizzare un'integrazione impostando la destinazione del percorso su un valore di
"integrations/, dove{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 WebSocket protocollo, 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.
