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à. # Crea percorsi per WebSocket APIs API Gateway Nella tua WebSocket API, i messaggi JSON in arrivo vengono indirizzati alle integrazioni di backend in base ai percorsi che configuri. (Messaggi non JSON sono indirizzati a una route `$default` configurata dall'utente). Una *route* include una *chiave di route*, che è il valore previsto dopo che un'*espressione di selezione della route* è stata valutata. `routeSelectionExpression` è un attributo definito a livello di API. Specifica una proprietà JSON che deve essere presente nel payload del messaggio. Per ulteriori informazioni sulle espressioni di selezione della route, consulta [Espressioni di selezione dell'instradamento](#apigateway-websocket-api-route-selection-expressions). Ad esempio, se i messaggi JSON contengono una proprietà `action` e desideri eseguire operazioni diverse in base a questa proprietà, l'espressione di selezione della route potrebbe essere `${request.body.action}`. La tabella di routing specifica quale operazione eseguire abbinando il valore della proprietà `action` ai valori delle chiavi route personalizzate definiti nella tabella. Esistono tre route predefinite che possono essere utilizzate: `$connect`, `$disconnect` e `$default`. Inoltre, puoi creare route personalizzate. + API Gateway chiama il `$connect` percorso quando viene avviata una connessione persistente tra il client e un' WebSocket API. + API Gateway chiama la route `$disconnect` quando il client o il server si scollega dall'API. + API Gateway chiama una route personalizzata dopo che l'espressione di selezione della route viene valutata rispetto al messaggio, se viene trovata una route corrispondente; la corrispondenza determina quale integrazione viene richiamata. + API Gateway chiama la route `$default` se l'espressione di selezione della route non può essere valutata rispetto al messaggio o se non viene trovata una route corrispondente. ## Espressioni di selezione dell'instradamento Un'*espressione di selezione dell'instradamento* viene valutata quando il servizio seleziona l'instradamento da seguire per un messaggio in entrata. Il servizio utilizza la route il cui `routeKey` corrisponde esattamente al valore valutato. Se non trova alcuna corrispondenza ed è disponibile una route con una chiave di routing `$default`, verrà selezionata. Se nessuna route corrisponde al valore valutato e non è disponibile una route `$default`, il servizio restituisce un errore. Per WebSocket based APIs, l'espressione deve avere il seguente formato`$request.body.{path_to_body_element}`. Supponiamo, ad esempio, che tu stia inviando il seguente messaggio JSON: ``` { "service" : "chat", "action" : "join", "data" : { "room" : "room1234" } } ``` Potresti decidere di selezionare il comportamento dell'API in base alla proprietà `action`. In questo caso, potresti definire la seguente espressione di selezione dell'instradamento: ``` $request.body.action ``` In questo esempio, `request.body` si riferisce al payload JSON del messaggio ed `.action` è un'[JSONPath](https://goessner.net/articles/JsonPath/)espressione. Puoi utilizzare qualsiasi espressione di percorso JSON dopo `request.body`, ma tieni presente che il risultato sarà in formato stringa. Ad esempio, se l' JSONPath espressione restituisce una matrice di due elementi, questo verrà presentato come stringa. `"[item1, item2]"` Per questo motivo, è opportuno che l'espressione restituisca un valore e non una matrice o un oggetto. Puoi semplicemente utilizzare un valore statico oppure utilizzare più variabili. La tabella seguente mostra esempi con i relativi risultati valutati per il payload precedente. | Espressione | Risultato valutato | Descrizione | | --- | --- | --- | | \$1request.body.action | join | Una variabile da cui è stato rimosso il wrapping | | \$1\$1request.body.action\$1 | join | Una variabile con wrapping | | \$1\$1request.body.service\$1/\$1\$1request.body.action\$1 | chat/join | Più variabili con valori statici | | \$1\$1request.body.action\$1-\$1\$1request.body.invalidPath\$1 | join- | Se non JSONPath viene trovato, la variabile viene risolta come «». | | action | action | Valore statico | | \$1\$1default | \$1default | Valore statico | Il risultato valutato viene utilizzato per trovare una route. Se esiste una route con una chiave di routing corrispondente, viene selezionato per elaborare il messaggio. Se non è possibile trovare una route corrispondente, API Gateway cerca di trovare la route `$default`, se disponibile. Se la route `$default` non è definita, API Gateway restituisce un errore. ## Configurare i percorsi per un' WebSocket API in API Gateway Quando crei per la prima volta una nuova WebSocket API, ci sono tre percorsi predefiniti: `$connect``$disconnect`, e`$default`. Puoi crearli utilizzando la console, l'API o AWS CLI. Se lo desideri, puoi creare instradamenti personalizzati. Per ulteriori informazioni, consulta [Panoramica di WebSocket APIs in API Gateway](apigateway-websocket-api-overview.md). **Nota** Nell'interfaccia a riga di comando, puoi creare instradamenti prima o dopo aver creato le integrazioni e puoi riutilizzare la stessa integrazione per più instradamenti. ### Creazione di una route tramite la console API Gateway **Per creare una route utilizzando la console API Gateway** 1. Accedere alla console API Gateway, scegliere l'API e selezionare **Routes (Route)**. 1. Seleziona **Crea instradamento**. 1. Per **Chiave instradamento** inserisci il nome della chiave instradamento. È possibile creare gli instradamenti predefiniti (`$connect`, `$disconnect` e `$default`) o un instradamento personalizzato. **Nota** Quando crei un instradamento personalizzato, non utilizzare il prefisso `$` nel nome della chiave di instradamento. Questo prefisso è riservato per gli instradamenti predefiniti. 1. Seleziona e configura il tipo di integrazione per l'instradamento. Per ulteriori informazioni, consulta [Configurare una richiesta di integrazione WebSocket API utilizzando la console API Gateway](apigateway-websocket-api-integration-requests.md#apigateway-websocket-api-integration-request-using-console). ### Crea un percorso utilizzando il AWS CLI Il comando [create-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route.html) seguente crea un instradamento: ``` aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default ``` L’output sarà simile al seguente: ``` { "ApiKeyRequired": false, "AuthorizationType": "NONE", "RouteKey": "$default", "RouteId": "1122334" } ``` ### Specifica delle impostazioni per la richiesta di instradamento per `$connect` Quando configuri l'instradamento `$connect` per la tua API, sono disponibili le seguenti impostazioni facoltative per abilitare l'autorizzazione per l'API. Per ulteriori informazioni, consulta [Instradamento `$connect`](apigateway-websocket-api-route-keys-connect-disconnect.md#apigateway-websocket-api-routes-about-connect). + **Authorization (Autorizzazione)**: se non è richiesta alcuna autorizzazione, puoi specificare `NONE`. In caso contrario, puoi specificare: + `AWS_IAM`per utilizzare le policy AWS IAM standard per controllare l'accesso alla tua API. + `CUSTOM` per implementare l'autorizzazione per un'API specificando una funzione di autorizzazione Lambda creata in precedenza. L'autorizzatore può risiedere nel tuo AWS account o in un altro AWS account. Per ulteriori informazioni sui provider di autorizzazioni Lambda, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). **Nota** Nella console API Gateway, l'impostazione `CUSTOM` è visibile solo dopo aver configurato una funzione di autorizzazione come descritto in [Configurazione di un sistema di autorizzazione Lambda (console)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console). **Importante** L'impostazione **Authorization (Autorizzazione)** viene applicata all'intera API, non solo all'instradamento `$connect`. L'instradamento `$connect` protegge gli altri instradamenti, perché viene chiamato per ogni connessione. + **Chiave API necessaria**: è possibile richiedere facoltativamente una chiave API per l'instradamento `$connect` di un'API. Puoi utilizzare le chiavi API insieme ai piani di utilizzo per controllare e tracciare l'accesso al tuo. APIs Per ulteriori informazioni, consulta [Piani di utilizzo e chiavi API per REST APIs in API Gateway](api-gateway-api-usage-plans.md). ### Configurazione della richiesta di instradamento `$connect` mediante la console API Gateway Per configurare la richiesta di `$connect` routing per un' WebSocket API utilizzando la console API Gateway: 1. Accedere alla console API Gateway, scegliere l'API e selezionare **Routes (Route)**. 1. In **Instradamenti** scegli `$connect` o crea un instradamento `$connect` seguendo [Creazione di una route tramite la console API Gateway](#apigateway-websocket-api-route-using-console). 1. Nella sezione **Impostazioni della richiesta di instradamento** scegli **Modifica**. 1. Per **Autorizzazione** seleziona un tipo di autorizzazione. 1. Per richiedere un'API per l'instradamento `$connect` seleziona **Richiedi chiave API**. 1. Scegli **Save changes** (Salva modifiche). # Imposta le risposte di routing per WebSocket APIs in API Gateway WebSocket le rotte possono essere configurate per comunicazioni bidirezionali o unidirezionali. API Gateway non trasferisce la risposta del back-end alla risposta di instradamento, a meno che non venga configurata una risposta di instradamento. **Nota** È possibile definire solo la risposta del `$default` percorso per. WebSocket APIs È possibile utilizzare una risposta di integrazione per manipolare la risposta da un servizio back-end. Per ulteriori informazioni, consulta [Panoramica delle risposte di integrazione](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-overview). Puoi configurare le risposte di routing e le espressioni di selezione delle risposte utilizzando la console API Gateway o il AWS CLI o un AWS SDK. Per ulteriori informazioni sulle espressioni di selezione delle risposte di instradamento, consulta [Espressioni di selezione della risposta di instradamento](apigateway-websocket-api-selection-expressions.md#apigateway-websocket-api-route-response-selection-expressions). **Topics** + [Configurazione di una risposta di instradamento mediante la console API Gateway](#apigateway-websocket-api-route-response-using-console) + [Imposta una risposta di routing utilizzando il AWS CLI](#apigateway-websocket-api-route-response-using-awscli) ## Configurazione di una risposta di instradamento mediante la console API Gateway Dopo aver creato un' WebSocket API e collegato una funzione proxy Lambda alla route predefinita, puoi configurare la risposta alla route utilizzando la console API Gateway: 1. Accedi alla console API Gateway, scegli un' WebSocket API con integrazione della funzione proxy Lambda sul `$default` percorso. 1. In **Routes** (Route), scegliere l'instradamento `$default`. 1. Scegli **Abilita la comunicazione bidirezionale**. 1. Seleziona **Deploy API (Distribuisci API)**. 1. Implementa l'API in una fase. Per connettersi all'API, utilizzare il seguente comando [wscat](https://www.npmjs.com/package/wscat). Per ulteriori informazioni su `wscat`, consultare [Utilizzalo `wscat` per connetterti a un' WebSocket API e inviarle messaggi](apigateway-how-to-call-websocket-api-wscat.md). ``` wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test ``` Premere il pulsante INVIO per chiamare l'instradamento predefinito. Il comando dovrebbe restituire il corpo della funzione Lambda. ## Imposta una risposta di routing utilizzando il AWS CLI Il [create-route-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route-response.html)comando seguente crea una risposta di rotta per la `$default` rotta. È possibile identificare l’ID dell’API e l’ID dell’instradamento utilizzando i comandi [get-apis](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-apis.html) e [get-routes](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-routes.html). ``` aws apigatewayv2 create-route-response \ --api-id aabbccddee \ --route-id 1122334 \ --route-response-key '$default' ``` L'output sarà simile al seguente: ``` { "RouteResponseId": "abcdef", "RouteResponseKey": "$default" } ``` # Imposta una `$connect` route che richiede un WebSocket sottoprotocollo I client possono utilizzare il `Sec-WebSocket-Protocol` campo per richiedere un [WebSocket sottoprotocollo](https://datatracker.ietf.org/doc/html/rfc6455#page-12) durante la connessione all'API. WebSocket È possibile impostare un'integrazione per la route `$connect` in modo da consentire le connessioni solo se un client richiede un sottoprotocollo supportato dall'API. La funzione Lambda di esempio seguente restituisce l'intestazione `Sec-WebSocket-Protocol` ai client. La funzione stabilisce una connessione all'API solo se il client specifica il sottoprotocollo `myprotocol`. Per un CloudFormation modello che crea questo esempio di integrazione tra API e proxy Lambda, consulta. [samples/ws-subprotocol.zip](samples/ws-subprotocol.zip) ``` export const handler = async (event) => { if (event.headers != undefined) { const headers = toLowerCaseProperties(event.headers); if (headers['sec-websocket-protocol'] != undefined) { const subprotocolHeader = headers['sec-websocket-protocol']; const subprotocols = subprotocolHeader.split(','); if (subprotocols.indexOf('myprotocol') >= 0) { const response = { statusCode: 200, headers: { "Sec-WebSocket-Protocol" : "myprotocol" } }; return response; } } } const response = { statusCode: 400 }; return response; }; function toLowerCaseProperties(obj) { var wrapper = {}; for (var key in obj) { wrapper[key.toLowerCase()] = obj[key]; } return wrapper; } ``` È possibile utilizzare [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat) per verificare che l'API consenta le connessioni solo se un client richiede un sottoprotocollo supportato dall'API. I comandi seguenti utilizzano il flag `-s` per specificare i sottoprotocolli durante la connessione. Il comando seguente tenta una connessione con un sottoprotocollo non supportato. Poiché il client ha specificato il sottoprotocollo `chat1`, l'integrazione Lambda restituisce un errore 400 e la connessione non riesce. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1 error: Unexpected server response: 400 ``` Il comando seguente include un sottoprotocollo supportato nella richiesta di connessione. L'integrazione Lambda consente la connessione. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1,myprotocol connected (press CTRL+C to quit) ``` Per ulteriori informazioni sull'invocazione WebSocket APIs, consulta. [Invoca WebSocket APIs](apigateway-how-to-call-websocket-api.md)