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à. # Sviluppa WebSocket APIs in API Gateway Questa sezione fornisce dettagli sulle funzionalità di API Gateway di cui hai bisogno durante lo sviluppo del tuo API Gateway APIs. Durante lo sviluppo delle API di API Gateway è possibile impostare una serie di caratteristiche dell'API. Queste caratteristiche dipendono dal caso d'uso dell'API. Ad esempio, è possibile consentire a solo a determinati client di richiamare l'API oppure che questa sia disponibile per tutti. È possibile decidere che una chiamata API esegua una funzione Lambda, una query a un database o richiami un'applicazione. **Topics** + [Crea WebSocket APIs in API Gateway](apigateway-websocket-api-create-empty-api.md) + [Tipi di indirizzo IP per API WebSocket in Gateway API](websocket-api-ip-address-type.md) + [Crea percorsi per WebSocket APIs API Gateway](websocket-api-develop-routes.md) + [Controlla e gestisci l'accesso WebSocket APIs a API Gateway](apigateway-websocket-api-control-access.md) + [Integrazioni per API WebSocket APIs Gateway](apigateway-websocket-api-integrations.md) + [Richiedi la convalida per WebSocket APIs in API Gateway](websocket-api-request-validation.md) + [Trasformazioni dei dati per API WebSocket APIs Gateway](websocket-api-data-transformations.md) + [Tipi di supporti binari per API WebSocket in Gateway API](websocket-api-develop-binary-media-types.md) + [Invoca WebSocket APIs](apigateway-how-to-call-websocket-api.md) # Crea WebSocket APIs in API Gateway Puoi creare un' WebSocket API nella console API Gateway, utilizzando il comando AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) o utilizzando il `CreateApi` comando in un AWS SDK. Le seguenti procedure mostrano come creare una nuova API. WebSocket **Nota** WebSocket APIs supporta solo TLS 1.2 e TLS 1.3. Le versioni precedenti di TLS non sono supportate. ## Crea un' WebSocket API utilizzando i comandi AWS CLI Il comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) seguente crea un’API con l’espressione di selezione dell’instradamento `$request.body.action`: ``` aws apigatewayv2 --region us-east-1 create-api --name "myWebSocketApi3" --protocol-type WEBSOCKET --route-selection-expression '$request.body.action' ``` L'output sarà simile al seguente: ``` { "ApiKeySelectionExpression": "$request.header.x-api-key", "Name": "myWebSocketApi3", "CreatedDate": "2018-11-15T06:23:51Z", "ProtocolType": "WEBSOCKET", "RouteSelectionExpression": "'$request.body.action'", "ApiId": "aabbccddee" } ``` ## Creare un' WebSocket API utilizzando la console API Gateway Puoi creare un' WebSocket API nella console scegliendo il WebSocket protocollo e assegnando un nome all'API. **Importante** Dopo aver creato l'API, non puoi modificare il protocollo scelto per la stessa. Non è possibile convertire un' WebSocket API in un'API REST o viceversa. **Per creare un' WebSocket API utilizzando la console API Gateway** 1. Accedere alla console API Gateway e scegliere **Create API (Crea API)**. 1. In **WebSocket API**, scegli **Build**. Sono supportati solo gli endpoint regionali. 1. In **Nome API** immetti il nome dell'API. 1. Per **Espressione di selezione dell'instradamento** immetti un valore. Ad esempio, `$request.body.action`. Per ulteriori informazioni sulle espressioni di selezione della route, consulta [Espressioni di selezione dell'instradamento](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions). 1. Esegui una delle seguenti operazioni: + Scegli **Crea API vuota** per creare un'API senza instradamenti. + Scegli **Successivo** per collegare gli instradamenti all'API. Puoi collegare gli instradamenti dopo aver creato l'API. # Tipi di indirizzo IP per API WebSocket in Gateway API Quando si crea un’API, è possibile specificare il tipo di indirizzo IP che può invocarla. È possibile scegliere IPv4 per risolvere gli indirizzi IPv4 per invocare l’API oppure dualstack per consentire a entrambi gli indirizzi IPv4 e IPv6 di invocare l’API. È consigliabile impostare il tipo di indirizzo IP su dualstack per ridurre l’esaurimento dello spazio IP o per il livello di sicurezza. Per ulteriori informazioni sui vantaggi del tipo di indirizzo IP dualstack, consultare [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html). ## Considerazioni sui tipi di indirizzo IP Le seguenti considerazioni potrebbero influire sull’utilizzo dei tipi di indirizzo IP: + Il tipo di indirizzo IP predefinito per tutte le API WebSocket è IPv4. + Se per un’API esistente si modifica il tipo di indirizzo IP da IPv4 a dualstack, è necessario verificare che tutte le policy che controllano l’accesso alle API siano aggiornate in modo da tenere conto delle chiamate IPv6. Quando si modifica il tipo di indirizzo IP, la modifica diventa immediatamente effettiva. + L’API può essere mappata su un nome di dominio personalizzato con un tipo di indirizzo IP diverso da quello dell’API. Se si disabilita l’endpoint API predefinito, si potrebbe influire sul modo in cui i chiamanti possono invocare l’API. ## Modifica del tipo di indirizzo IP di un’API WebSocket È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell’API. È possibile aggiornare la configurazione dell’API utilizzando la Console di gestione AWS, AWS CLI, CloudFormation o un AWS SDK. Se si modifica il tipo di indirizzo IP dell’API, non è necessario eseguire di nuovo l’implementazione dell’API per rendere effettive le modifiche. ------ #### [ Console di gestione AWS ] **Per modificare il tipo di indirizzo IP di un’API WebSocket** 1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Scegli un'API WebSocket. 1. Scegliere **Impostazioni API**, quindi scegliere **Modifica**. 1. Per Tipo di indirizzo IP, selezionare **IPv4** o **Dualstack**. 1. Selezionare **Salva**. La modifica alla configurazione dell’API ha effetto immediato. ------ #### [ AWS CLI ] Il comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) seguente aggiorna un’API in modo che abbia un tipo di indirizzo IP dualstack: ``` aws apigatewayv2 update-api \ --api-id abcd1234 \ --ip-address-type dualstack ``` L'output sarà simile al seguente: ``` { "ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com", "ApiId": "abcd1234", "ApiKeySelectionExpression": "$request.header.x-api-key", "CreatedDate": "2025-02-04T22:20:20+00:00", "DisableExecuteApiEndpoint": false, "Name": "My-WebSocket-API", "ProtocolType": "WEBSOCKET", "RouteSelectionExpression": "$request.method $request.path", "Tags": {}, "NotificationUris": [], "IpAddressType": "dualstack" } ``` ------ # 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) # Controlla e gestisci l'accesso WebSocket APIs a API Gateway API Gateway supporta diversi meccanismi per il controllo e la gestione dell'accesso all' WebSocket API. Puoi usare i seguenti meccanismi per l'autenticazione e l'autorizzazione: + **I ruoli e le policy AWS IAM standard** offrono controlli di accesso flessibili e robusti. Puoi utilizzare i ruoli e le policy IAM per controllare chi può creare e gestire APIs i tuoi e chi può richiamarli. Per ulteriori informazioni, consulta [Controlla l'accesso a WebSocket APIs con l'autorizzazione IAM](apigateway-websocket-control-access-iam.md). + I **tag IAM** possono essere utilizzati insieme alle policy IAM per controllare l'accesso. Per ulteriori informazioni, consulta [Utilizzo dei tag per controllare l'accesso alle risorse REST API di Gateway API](apigateway-tagging-iam-policy.md). + **Gli autorizzatori Lambda sono** funzioni Lambda che controllano l'accesso a. APIs Per ulteriori informazioni, consulta [Controlla l'accesso WebSocket APIs con gli autorizzatori AWS Lambda REQUEST](apigateway-websocket-api-lambda-auth.md). Per migliorare il tuo livello di sicurezza, ti consigliamo di configurare un autorizzatore per il `$connect` percorso su tutti i tuoi. WebSocket APIs Potrebbe essere necessario eseguire questa operazione per rispettare vari framework di conformità. Per ulteriori informazioni, consultare [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) nella *Guida per l’utente di AWS Security Hub *. **Topics** + [Controlla l'accesso a WebSocket APIs con l'autorizzazione IAM](apigateway-websocket-control-access-iam.md) + [Controlla l'accesso WebSocket APIs con gli autorizzatori AWS Lambda REQUEST](apigateway-websocket-api-lambda-auth.md) # Controlla l'accesso a WebSocket APIs con l'autorizzazione IAM L'autorizzazione IAM in WebSocket APIs è simile a quella per [REST APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md), con le seguenti eccezioni: + L'azione `execute-api` supporta `ManageConnections` oltre alle azioni esistenti (`Invoke`, `InvalidateCache`). `ManageConnections` controlla l'accesso all'API @connections. + WebSocket i percorsi utilizzano un formato ARN diverso: ``` arn:aws:execute-api:region:account-id:api-id/stage-name/route-key ``` + L'`@connections`API utilizza lo stesso formato ARN di REST: APIs ``` arn:aws:execute-api:region:account-id:api-id/stage-name/POST/@connections ``` **Importante** Quando usi l'[autorizzazione IAM](#apigateway-websocket-control-access-iam) è necessario firmare le richieste con [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Puoi, ad esempio, configurare la seguente policy per il client. Questo esempio consente a chiunque di inviare un messaggio (`Invoke`) per tutti gli instradamenti ad eccezione di un instradamento segreto nella fase `prod` e impedisce l'invio di un messaggio da qualunque utente ai client connessi (`ManageConnections`) in tutte le fasi. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/prod/*" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/prod/secret" ] }, { "Effect": "Deny", "Action": [ "execute-api:ManageConnections" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/*" ] } ] } ``` ------ # Controlla l'accesso WebSocket APIs con gli autorizzatori AWS Lambda REQUEST Una funzione di autorizzazione Lambda in WebSocket APIs è simile a quella di [REST APIs](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create), con le seguenti eccezioni: + È possibile usare solo una funzione di autorizzazione Lambda per l'instradamento `$connect`. + Non è possibile utilizzare variabili di percorso (`event.pathParameters`), perché il percorso è fisso. + `event.methodArn` è diverso dall'API REST equivalente, perché non ha un metodo HTTP. Nel caso di `$connect`, `methodArn` termina con `"$connect"`: ``` arn:aws:execute-api:region:account-id:api-id/stage-name/$connect ``` + Le variabili di contesto in `event.requestContext` sono diverse da quelle di REST. APIs L'esempio seguente mostra un input a un `REQUEST` autorizzatore per un' WebSocket API: ``` { "type": "REQUEST", "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/default/$connect", "headers": { "Connection": "upgrade", "content-length": "0", "HeaderAuth1": "headerValue1", "Host": "abcdef123.execute-api.us-east-1.amazonaws.com", "Sec-WebSocket-Extensions": "permessage-deflate; client_max_window_bits", "Sec-WebSocket-Key": "...", "Sec-WebSocket-Version": "13", "Upgrade": "websocket", "X-Amzn-Trace-Id": "...", "X-Forwarded-For": "...", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https" }, "multiValueHeaders": { "Connection": [ "upgrade" ], "content-length": [ "0" ], "HeaderAuth1": [ "headerValue1" ], "Host": [ "abcdef123.execute-api.us-east-1.amazonaws.com" ], "Sec-WebSocket-Extensions": [ "permessage-deflate; client_max_window_bits" ], "Sec-WebSocket-Key": [ "..." ], "Sec-WebSocket-Version": [ "13" ], "Upgrade": [ "websocket" ], "X-Amzn-Trace-Id": [ "..." ], "X-Forwarded-For": [ "..." ], "X-Forwarded-Port": [ "443" ], "X-Forwarded-Proto": [ "https" ] }, "queryStringParameters": { "QueryString1": "queryValue1" }, "multiValueQueryStringParameters": { "QueryString1": [ "queryValue1" ] }, "stageVariables": {}, "requestContext": { "routeKey": "$connect", "eventType": "CONNECT", "extendedRequestId": "...", "requestTime": "19/Jan/2023:21:13:26 +0000", "messageDirection": "IN", "stage": "default", "connectedAt": 1674162806344, "requestTimeEpoch": 1674162806345, "identity": { "sourceIp": "..." }, "requestId": "...", "domainName": "abcdef123.execute-api.us-east-1.amazonaws.com", "connectionId": "...", "apiId": "abcdef123" } } ``` Il seguente esempio di funzione di autorizzazione Lambda è una WebSocket versione della funzione di autorizzazione Lambda per REST in: APIs [Esempi aggiuntivi di funzioni del sistema di autorizzazione Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create) ------ #### [ Node.js ] ``` // A simple REQUEST authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter // in the request context match the specified values of // of 'headerValue1' and 'queryValue1' respectively. export const handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var stageVariables = event.stageVariables; var requestContext = event.requestContext; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var ApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var route = apiGatewayArnTmp[2]; // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. var authResponse = {}; var condition = {}; condition.IpAddress = {}; if (headers.HeaderAuth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback(null, generateDeny('me', event.methodArn)); } } // Helper function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17 '; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); } ``` ------ #### [ Python ] ``` # A simple REQUEST authorizer example to demonstrate how to use request # parameters to allow or deny a request. In this example, a request is # authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter # in the request context match the specified values of # of 'headerValue1' and 'queryValue1' respectively. import json def lambda_handler(event, context): print(event) # Retrieve request parameters from the Lambda function input: headers = event['headers'] queryStringParameters = event['queryStringParameters'] stageVariables = event['stageVariables'] requestContext = event['requestContext'] # Parse the input for the parameter values tmp = event['methodArn'].split(':') apiGatewayArnTmp = tmp[5].split('/') awsAccountId = tmp[4] region = tmp[3] ApiId = apiGatewayArnTmp[0] stage = apiGatewayArnTmp[1] route = apiGatewayArnTmp[2] # Perform authorization to return the Allow policy for correct parameters # and the 'Unauthorized' error, otherwise. authResponse = {} condition = {} condition['IpAddress'] = {} if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters["QueryString1"] == "queryValue1"): response = generateAllow('me', event['methodArn']) print('authorized') return json.loads(response) else: response = generateDeny('me', event['methodArn']) print('unauthorized') return json.loads(response) # Help function to generate IAM policy def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17 ' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } authResponse_JSON = json.dumps(authResponse) return authResponse_JSON def generateAllow(principalId, resource): return generatePolicy(principalId, 'Allow', resource) def generateDeny(principalId, resource): return generatePolicy(principalId, 'Deny', resource) ``` ------ [Per configurare la precedente funzione Lambda come funzione di autorizzazione per `REQUEST` WebSocket un'API, segui la stessa procedura utilizzata per REST. APIs](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console) Per configurare la route`$connect` per l'utilizzo di questo provider di autorizzazioni Lambda nella console, seleziona o crea la route `$connect`. Nella sezione **Impostazioni della richiesta di instradamento** scegli **Modifica**. Seleziona l'autorizzazione nel menu a discesa **Autorizzazione**, quindi scegli **Salva modifiche**. Per verificare l'autorizzatore, è necessario creare una nuova connessione. La modifica dell'autorizzatore in `$connect` non influisce sul client già connesso. Quando ti connetti alla tua WebSocket API, devi fornire valori per tutte le fonti di identità configurate. Ad esempio, puoi connetterti inviando una stringa di query e un'intestazione valide utilizzando `wscat` come nell'esempio seguente: ``` wscat -c 'wss://myapi.execute-api.us-east-1.amazonaws.com/beta?QueryString1=queryValue1' -H HeaderAuth1:headerValue1 ``` Se tenti di connetterti senza un valore di identità valido, riceverai una risposta `401`: ``` wscat -c wss://myapi.execute-api.us-east-1.amazonaws.com/beta error: Unexpected server response: 401 ``` # Integrazioni per API WebSocket APIs Gateway Dopo aver impostato una route API, devi integrarla con un endpoint nel back-end. Un endpoint di backend viene anche definito endpoint di integrazione e può essere una funzione Lambda, un endpoint HTTP o un'azione di servizio. AWS L'integrazione dell'API dispone di una richiesta e di una risposta di integrazione. In questa sezione, puoi imparare come configurare le richieste di integrazione e le risposte di integrazione per la tua API. WebSocket **Topics** + [Configurare una richiesta di integrazione WebSocket API in API Gateway](apigateway-websocket-api-integration-requests.md) + [Configurare una risposta di integrazione WebSocket API in API Gateway](apigateway-websocket-api-integration-responses.md) # Configurare una richiesta di integrazione WebSocket API in API Gateway La configurazione di una richiesta di integrazione comporta le seguenti operazioni: + Selezione di una chiave di instradamento da integrare nel back-end. + Specificazione dell'endpoint di backend da richiamare. WebSocket APIs supporta i seguenti tipi di integrazione: + `AWS_PROXY` + `AWS` + `HTTP_PROXY` + `HTTP` + `MOCK` Per ulteriori informazioni sui tipi di integrazione, consulta [IntegrationType](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)l'API REST di API Gateway V2. + Configurazione della modalità di trasformazione dei dati della richiesta di instradamento, se necessario, in dati di richiesta di integrazione specificando uno o più modelli di richiesta. ## Configurare una richiesta di integrazione WebSocket API utilizzando la console API Gateway **Per aggiungere una richiesta di integrazione a un percorso in un' WebSocket API utilizzando la console API Gateway** 1. Accedere alla console API Gateway, scegliere l'API e selezionare **Routes (Route)**. 1. In **Routes (Route)**, scegliere la route. 1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** nella sezione **Impostazioni della richiesta di integrazione**. 1. Per **Tipo di integrazione** scegli una delle seguenti opzioni: + Scegli **la funzione Lambda** solo se la tua API sarà integrata con una AWS Lambda funzione che hai già creato in questo account o in un altro account. **Per creare una nuova funzione Lambda in AWS Lambda, impostare un'autorizzazione di risorsa sulla funzione Lambda o eseguire qualsiasi altra azione del servizio Lambda, scegli invece Service.AWS ** + Scegliere **HTTP** se l'API verrà integrata con un endpoint HTTP esistente. Per ulteriori informazioni, consulta [Integrazioni HTTP per REST APIs in API Gateway](setup-http-integrations.md). + Scegliere **Mock (Fittizio)** se si desidera generare le risposte API direttamente da API Gateway, senza la necessità di un back-end di integrazione. Per ulteriori informazioni, consulta [Integrazioni fittizie per REST APIs in API Gateway](how-to-mock-integration.md). + Scegli **AWS service** se la tua API sarà integrata con un servizio. AWS + Scegli **Collegamento VPC** se l'API utilizzerà un `VpcLink` come endpoint di integrazione privato. Per ulteriori informazioni, consulta [Configura un'integrazione privata](set-up-private-integration.md). 1. Se scegli **Funzione Lambda** procedi come segue: 1. Per **Utilizza integrazione proxy Lambda** seleziona la casella di controllo desiderata per utilizzare l'[integrazione proxy Lambda](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy) o l'[integrazione proxy Lambda tra più account](apigateway-cross-account-lambda-integrations.md). 1. Per **Funzione Lambda** specifica la funzione in uno dei modi seguenti: + Se la funzione Lambda si trova nello stesso account, immetti il nome della funzione e quindi seleziona la funzione dall'elenco a discesa. **Nota** Il nome della funzione può facoltativamente includere l'alias o la specifica della versione, come in `HelloWorld`, `HelloWorld:1` o `HelloWorld:alpha`. + Se la funzione si trova in un account diverso, immettere l'ARN per la funzione. 1. Per utilizzare il valore di timeout predefinito di 29 secondi, mantieni attiva l'opzione **Timeout predefinito**. Per impostare un timeout personalizzato, scegli **Timeout predefinito** e immetti un valore di timeout compreso tra `50` e `29000` millisecondi. 1. Se si sceglie **HTTP**, seguire le istruzioni nella fase 4 di [Configurazione di una richiesta di integrazione API tramite la console API Gateway](how-to-method-settings-console.md). 1. Se si sceglie **Mock (Fittizio)**, andare alla fase **Request Templates (Modelli di richiesta)**. 1. Se scegli **Servizio AWS ** segui le istruzioni della fase 6 in [Configurazione di una richiesta di integrazione API tramite la console API Gateway](how-to-method-settings-console.md). 1. Se scegli **Collegamento VPC** procedi come segue: 1. Per **Integrazione proxy VPC** seleziona la casella di controllo se desideri eseguire il proxy delle richieste sull'endpoint di `VPCLink`. 1. Per **HTTP method (Metodo HTTP)** scegliere il tipo di metodo HTTP che corrisponde maggiormente al metodo nel back-end HTTP. 1. Dall'elenco a discesa **Collegamento VPC** seleziona un collegamento VPC. È possibile selezionare `[Use Stage Variables]` e inserire **\$1\$1stageVariables.vpcLinkId\$1** nella casella di testo sotto l'elenco. È possibile definire la variabile di fase `vpcLinkId` dopo l'implementazione dell'API in una fase e l'impostazione del suo valore sull'ID del `VpcLink`. 1. In **Endpoint URL (URL endpoint)**, immettere l'URL del back-end HTTP che l'integrazione deve utilizzare. 1. Per utilizzare il valore di timeout predefinito di 29 secondi, mantieni attiva l'opzione **Timeout predefinito**. Per impostare un timeout personalizzato, scegli **Timeout predefinito** e immetti un valore di timeout compreso tra `50` e `29000` millisecondi. 1. Scegli **Save changes** (Salva modifiche). 1. In **Modelli di richiesta** procedi come segue: 1. Per immettere un'**Espressione di selezione del modello** scegli **Modifica** in **Modelli di richiesta**. 1. Immetti un'**Espressione di selezione del modello**. Specifica un'espressione che viene ricercata da Gateway API nel payload del messaggio. Se viene trovata, viene valutata e il risultato è un valore chiave del modello che viene utilizzato per selezionare il modello di mappatura dei dati che deve essere applicato ai dati nel payload del messaggio. Il modello di mappatura dei dati viene creato nel passaggio successivo. Scegli **Modifica** per salvare le modifiche. 1. Scegli **Crea modello** per creare il modello di mappatura dei dati. Per **Chiave del modello** immetti il valore della chiave del modello utilizzato per selezionare il modello di mappatura dei dati da applicare ai dati nel payload del messaggio. Quindi, specifica un modello di mappatura. Scegli **Crea modello**. Per ulteriori informazioni sulle espressioni di selezione del modello, consulta [Espressioni di selezione del modello](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions). ## Imposta una richiesta di integrazione utilizzando il AWS CLI È possibile impostare una richiesta di integrazione per un percorso in un' WebSocket API utilizzando AWS CLI come illustrato nell'esempio seguente, che crea un'integrazione fittizia: 1. Crea un file denominato `integration-params.json`, con i seguenti contenuti: ``` {"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"} ``` 1. Utilizza il seguente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) per creare l’integrazione fittizia. ``` aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json ``` L'output sarà simile al seguente: ``` { "PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "IntegrationResponseSelectionExpression": "${response.statuscode}", "RequestTemplates": { "application/json": "{\"statusCode\":200}" }, "IntegrationId": "0abcdef", "IntegrationType": "MOCK" } ``` In alternativa, è possibile impostare una richiesta di integrazione per un'integrazione proxy utilizzando il AWS CLI. 1. Creare una funzione Lambda nella console Lambda e assegnarle un ruolo di esecuzione Lambda di base. 1. Utilizza il seguente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) per creare l’integrazione. ``` aws apigatewayv2 create-integration --api-id aabbccddee --integration-type AWS_PROXY --integration-method POST --integration-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations ``` L'output sarà simile al seguente: ``` { "PassthroughBehavior": "WHEN_NO_MATCH", "IntegrationMethod": "POST", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "IntegrationUri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations", "IntegrationId": "abcdefg", "IntegrationType": "AWS_PROXY" } ``` ## Formato di input di una funzione Lambda per l'integrazione del proxy per WebSocket APIs Con l'integrazione proxy Lambda, API Gateway mappa l'intera richiesta client al parametro di input `event` della funzione Lambda di back-end. Nell'esempio seguente viene illustrata la struttura dell'evento di input dall'instradamento `$connect` e dell'evento di input dall'instradamento `$disconnect` che Gateway API invia a un'integrazione proxy Lambda. ------ #### [ Input from the \$1connect route ] ``` { headers: { Host: 'abcd123.execute-api.us-east-1.amazonaws.com', 'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits', 'Sec-WebSocket-Key': '...', 'Sec-WebSocket-Version': '13', 'X-Amzn-Trace-Id': '...', 'X-Forwarded-For': '192.0.2.1', 'X-Forwarded-Port': '443', 'X-Forwarded-Proto': 'https' }, multiValueHeaders: { Host: [ 'abcd123.execute-api.us-east-1.amazonaws.com' ], 'Sec-WebSocket-Extensions': [ 'permessage-deflate; client_max_window_bits' ], 'Sec-WebSocket-Key': [ '...' ], 'Sec-WebSocket-Version': [ '13' ], 'X-Amzn-Trace-Id': [ '...' ], 'X-Forwarded-For': [ '192.0.2.1' ], 'X-Forwarded-Port': [ '443' ], 'X-Forwarded-Proto': [ 'https' ] }, requestContext: { routeKey: '$connect', eventType: 'CONNECT', extendedRequestId: 'ABCD1234=', requestTime: '09/Feb/2024:18:11:43 +0000', messageDirection: 'IN', stage: 'prod', connectedAt: 1707502303419, requestTimeEpoch: 1707502303420, identity: { sourceIp: '192.0.2.1' }, requestId: 'ABCD1234=', domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com', connectionId: 'AAAA1234=', apiId: 'abcd1234' }, isBase64Encoded: false } ``` ------ #### [ Input from the \$1disconnect route ] ``` { headers: { Host: 'abcd1234.execute-api.us-east-1.amazonaws.com', 'x-api-key': '', 'X-Forwarded-For': '', 'x-restapi': '' }, multiValueHeaders: { Host: [ 'abcd1234.execute-api.us-east-1.amazonaws.com' ], 'x-api-key': [ '' ], 'X-Forwarded-For': [ '' ], 'x-restapi': [ '' ] }, requestContext: { routeKey: '$disconnect', disconnectStatusCode: 1005, eventType: 'DISCONNECT', extendedRequestId: 'ABCD1234=', requestTime: '09/Feb/2024:18:23:28 +0000', messageDirection: 'IN', disconnectReason: 'Client-side close frame status not set', stage: 'prod', connectedAt: 1707503007396, requestTimeEpoch: 1707503008941, identity: { sourceIp: '192.0.2.1' }, requestId: 'ABCD1234=', domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com', connectionId: 'AAAA1234=', apiId: 'abcd1234' }, isBase64Encoded: false } ``` ------ # Configurare una risposta di integrazione WebSocket API in API Gateway La sezione seguente fornisce una breve panoramica delle risposte di integrazione per l' WebSocket API e su come impostare una risposta di integrazione per un' WebSocket API. **Topics** + [Panoramica delle risposte di integrazione](#apigateway-websocket-api-integration-response-overview) + [Risposte di integrazione per la comunicazione bidirezionale](#apigateway-websocket-api-integration-response-for-two-way-communication) + [Configurazione di una risposta di integrazione mediante la console API Gateway](#apigateway-websocket-api-integration-response-using-console) + [Imposta una risposta di integrazione utilizzando il AWS CLI](#apigateway-websocket-api-integration-response-using-awscli) ## Panoramica delle risposte di integrazione La risposta di integrazione di API Gateway è un metodo di creazione di modelli e di manipolazione della risposta da un servizio di back-end. Esistono alcune differenze nella configurazione di un'API REST rispetto a una risposta di integrazione WebSocket API, ma concettualmente il comportamento è lo stesso. WebSocket le rotte possono essere configurate per la comunicazione bidirezionale o unidirezionale. + Quando una route è configurata per la comunicazione bidirezionale, una risposta di integrazione consente di configurare le trasformazioni sul payload del messaggio restituito, in modo simile alle risposte di integrazione per REST. APIs + Se una route è configurata per la comunicazione unidirezionale, indipendentemente dalla configurazione della risposta di integrazione, non verrà restituita alcuna risposta sul WebSocket canale dopo l'elaborazione del messaggio. API Gateway non trasferisce la risposta del back-end alla risposta di instradamento, a meno che non venga configurata una risposta di instradamento. Per informazioni sull'impostazione di una risposta di instradamento, consultare [Imposta le risposte di routing per WebSocket APIs in API Gateway](apigateway-websocket-api-route-response.md). ## Risposte di integrazione per la comunicazione bidirezionale Le integrazioni possono essere divise in integrazioni *proxy* e integrazioni *non proxy*. **Importante** Per le *integrazioni proxy*, API Gateway trasferisce automaticamente l'output del back-end all’intermediario come payload completo. Non esiste alcuna risposta di integrazione. Per *integrazioni non proxy*, è necessario configurare almeno una risposta di integrazione: + Idealmente, una delle risposte di integrazione deve agire come un metodo catch-all quando non è possibile effettuare una scelta esplicita. Questo caso predefinito viene rappresentato impostando una chiave di risposta di integrazione di `$default`. + In tutti gli altri casi, la chiave di risposta di integrazione funziona come un'espressione regolare. Il formato adottato è `"/expression/"`. Per integrazioni HTTP non proxy: + API Gateway tenterà di trovare una corrispondenza con il codice di stato HTTP della risposta di back-end. In questo caso, la chiave di risposta di integrazione funzionerà come un'espressione regolare. Se non è possibile trovare una corrispondenza, viene scelta `$default` come risposta di integrazione. + L'espressione di selezione del modello, come descritto in precedenza, funziona in modo identico. Ad esempio: + `/2\d\d/`: ricevi e trasforma risposte andate a buon fine + `/4\d\d/`: ricevi e trasforma errori di richiesta non valida + `$default`: ricevi e trasforma tutte le risposte impreviste Per ulteriori informazioni sulle espressioni di selezione del modello, consultare [Espressioni di selezione del modello](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions). ## Configurazione di una risposta di integrazione mediante la console API Gateway Per configurare una risposta di integrazione del percorso per un' WebSocket API utilizzando la console API Gateway: 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegli la tua WebSocket API e scegli il tuo percorso. 1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Crea risposta di integrazione** nella sezione **Impostazioni della risposta di integrazione**. 1. Per **Chiave della risposta** inserisci un valore che verrà individuato nella chiave della risposta del messaggio in uscita dopo aver valutato l'espressione di selezione di risposta. Ad esempio, puoi inserire **/4\$1d\$1d/** per ricevere e trasformare gli errori di richiesta non valida o **\$1default** per ricevere e trasformare tutte le risposte che corrispondono all'espressione di selezione del modello. 1. Per **Espressione di selezione del modello** immetti un'espressione di selezione per valutare il messaggio in uscita. 1. Scegli **Crea risposta**. 1. È inoltre possibile definire un modello di mappatura per configurare le trasformazioni del payload dei messaggi restituiti. Scegli **Crea modello**. 1. Immettere un nome per la chiave. Se è stata scelta l'espressione di selezione del modello predefinita, immettere**\$1\$1default**. 1. Per **Modello della risposta** immetti il modello di mappatura nell'editor di codice. 1. Scegli **Crea modello**. 1. Scegli **Implementa API** per implementare l'API. 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 ``` Quando viene richiamato l'instradamento, dovrebbe venire restituito il payload del messaggio restituito. ## Imposta una risposta di integrazione utilizzando il AWS CLI Il [create-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration-response.html)comando seguente crea una risposta di `$default` integrazione: ``` aws apigatewayv2 create-integration-response \ --api-id vaz7da96z6 \ --integration-id a1b2c3 \ --integration-response-key '$default' ``` # Richiedi la convalida per WebSocket APIs in API Gateway 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 una risposta gateway «Bad request body» al client e pubblica i risultati della convalida in Logs. CloudWatch L'utilizzo della convalida in questo modo riduce le chiamate non necessarie al back-end dell'API. ## Espressioni di selezione del modello Puoi utilizzare un'espressione di selezione del modello per convalidare dinamicamente le richieste all'interno della stessa route. La convalida del modello si verifica se si fornisce un'espressione di selezione del modello per integrazioni proxy o non proxy. Potrebbe essere necessario definire il modello `$default` come un fallback quando non viene trovato alcun modello corrispondente. Se non esiste un modello corrispondente e `$default` non è definito, la convalida non va a buon fine. L'aspetto dell'espressione di selezione è simile a `Route.ModelSelectionExpression` e valuta la chiave per `Route.RequestModels`. *Quando definisci un percorso per un' WebSocket API, puoi facoltativamente specificare un'espressione di selezione del modello.* Questa espressione viene valutata per selezionare il modello da utilizzare per la convalida del corpo quando si riceve una richiesta. L'espressione restituisce una delle voci presenti nel di una route [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels). Un modello viene espresso come [schema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) e descrive la struttura dati del corpo della richiesta. La natura di queste espressioni di selezione consente di scegliere in modo dinamico il modello in base al quale eseguire la convalida in fase di runtime per una determinata route. Per informazioni su come creare un modello, consulta [Modelli di dati per REST APIs](models-mappings-models.md). ## Configurazione della convalida delle richieste tramite la console Gateway Amazon API L'esempio seguente mostra come configurare la convalida delle richieste per un instradamento. Innanzitutto, si crea un modello e quindi un instradamento. Successivamente, si configura la convalida delle richieste sull'instradamento appena creato. Infine, si implementa e si esegue il test dell'API. Per completare questo tutorial, è necessaria un' WebSocket API `$request.body.action` come espressione di selezione del percorso e un endpoint di integrazione per la nuova rotta. Per la connessione all'API è inoltre necessario `wscat`. Per ulteriori informazioni, consulta [Utilizzalo `wscat` per connetterti a un' WebSocket API e inviarle messaggi](apigateway-how-to-call-websocket-api-wscat.md). **Creazione di un modello** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegli un'API. WebSocket 1. Nel riquadro di navigazione principale seleziona **Modelli**. 1. Scegli **Crea modello**. 1. In **Nome**, inserisci **emailModel**. 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Schema modello** immetti il seguente modello: ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type" : "object", "required" : [ "address"], "properties" : { "address": { "type": "string" } } } ``` Per questo modello è necessario che la richiesta contenga un indirizzo e-mail. 1. Scegli **Save** (Salva). In questo passaggio, crei un percorso per la tua WebSocket API. **Come creare una route** 1. Nel pannello di navigazione principale scegli **Instradamenti**. 1. Selezionare **Create Route (Crea route)**. 1. Per **Chiave instradamento**, inserisci **sendMessage**. 1. Scegli un tipo di integrazione e specificare un endpoint di integrazione. Per ulteriori informazioni, consulta [Integrazioni per API WebSocket APIs Gateway](apigateway-websocket-api-integrations.md). 1. Selezionare **Create Route (Crea route)**. In questo passaggio si imposta la convalida delle richieste per l'instradamento `sendMessage`. **Per impostare la convalida delle richieste** 1. Nella scheda **Richiesta di instradamento**, scegli **Modifica** in **Impostazioni della richiesta di instradamento**. 1. Per **Espressione di selezione del modello** immetti **\$1\$1request.body.messageType\$1**. Gateway API utilizza la proprietà `messageType` per convalidare la richiesta in arrivo. 1. Scegli **Aggiungi modello di richiesta**. 1. Per **Chiave modello** inserisci **email**. 1. Per **Modello** scegli **emailModel**. Gateway API convalida i messaggi in arrivo con la proprietà `messageType` impostata su `email` per questo modello. **Nota** Se Gateway API non riesce ad abbinare l'espressione di selezione del modello a una chiave del modello, viene selezionato il modello `$default`. Se non esiste un modello `$default`, la convalida non va a buon fine. Per la produzione APIs, ti consigliamo di creare un `$default` modello. 1. Scegli **Save changes** (Salva modifiche). In questo passaggio si implementa e si testa l'API. **Per distribuire e testare l'API** 1. Seleziona **Deploy API (Distribuisci API)**. 1. Scegliere la fase desiderata dall'elenco a discesa oppure immettere il nome di una nuova fase. 1. Seleziona **Implementa**. 1. Nel riquadro di navigazione principale scegli **Fasi**. 1. Copia l' WebSocket URL della tua API. L'URL dovrebbe essere del tipo `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production`. 1. Apri un nuovo terminale ed eseguire il comando **wscat** con i parametri seguenti. ``` wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production ``` ``` Connected (press CTRL+C to quit) ``` 1. Utilizza il seguente comando per testare l'API. ``` {"action": "sendMessage", "messageType": "email"} ``` ``` {"message": "Invalid request body", "connectionId":"ABCD1=234", "requestId":"EFGH="} ``` Gateway API non riuscirà a completare la richiesta. Utilizza il seguente comando per inviare una richiesta valida all'API. ``` {"action": "sendMessage", "messageType": "email", "address": "mary_major@example.com"} ``` # Trasformazioni dei dati per API WebSocket APIs Gateway In API Gateway, la richiesta del metodo di un' WebSocket API può accettare un payload in un formato diverso dal payload della richiesta di integrazione corrispondente, come richiesto nel backend. Analogamente, il back-end potrebbe restituire un payload delle risposta di integrazione diverso dal payload della risposta di metodo, in base alle aspettative del front-end. Gateway API consente di utilizzare le trasformazioni dei modelli di mappatura per mappare il payload da una richiesta di metodo alla richiesta di integrazione corrispondente e da una risposta di integrazione alla corrispondente risposta di metodo. Si crea un modello di mappatura e si specifica un’espressione di selezione del modello per determinare quale modello utilizzare per eseguire le trasformazioni dei dati necessarie. È possibile utilizzare le mappature dei dati per mappare i dati da una [richiesta di instradamento](api-gateway-basic-concept.md#apigateway-definition-route-request) a un'integrazione back-end. Per ulteriori informazioni, consulta [Configurare la mappatura dei dati per API WebSocket APIs Gateway](websocket-api-data-mapping.md). ## Modelli di mappatura e modelli [Un *modello di mappatura* è uno script espresso in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e applicato al payload utilizzando espressioni. JSONPath ](https://goessner.net/articles/JsonPath/) Per ulteriori informazioni sui modelli di mappatura API Gateway, consulta [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). Il payload può avere un *modello di dati* in base alla [bozza 4 dello schema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). Per generare un modello di mappatura, non è necessario definire un modello. Tuttavia, un modello può essere utile per crearne un altro, poiché API Gateway genera un piano di modello in base a un modello fornito. Per ulteriori informazioni sui modelli API Gateway, consulta [Modelli di dati per REST APIs](models-mappings-models.md). ## Espressioni di selezione del modello [[Per trasformare un payload con un modello di mappatura, è necessario specificare un'espressione di selezione del modello WebSocket API in una richiesta di integrazione o in una risposta di integrazione.](apigateway-websocket-api-integration-responses.md)](apigateway-websocket-api-integration-requests.md) Questa espressione viene valutata per determinare il modello di input o di output (se disponibili) da usare per trasformare il corpo della richiesta nel corpo della richiesta di integrazione (tramite un modello di input) o il corpo della risposta di integrazione nel corpo della risposta di instradamento (tramite un modello di output). `Integration.TemplateSelectionExpression` supporta `${request.body.jsonPath}` e valori statici. `IntegrationResponse.TemplateSelectionExpression` supporta `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` e valori statici. ## Espressioni di selezione della risposta di integrazione Quando [imposti una risposta di integrazione per un'](apigateway-websocket-api-integration-responses.md) WebSocket API, puoi facoltativamente specificare un'espressione di selezione della risposta di integrazione. Questa espressione determina quale `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` deve essere selezionata quando viene restituita un'integrazione. Il valore di questa espressione è attualmente limitato da API Gateway, come definito di seguito. Tieni presente che questa espressione è rilevante solo per le *integrazioni non proxy*; un'integrazione proxy restituisce semplicemente il payload della risposta all'intermediario senza alcuna modellazione o modifica. A differenza di altre espressioni di selezione precedenti, questa espressione supporta attualmente un formato di *corrispondenza di modelli*. L'espressione deve essere racchiusa tra barre. Attualmente il valore è fisso e dipende dal valore di `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`: + Per le integrazioni basate su Lambda, è `$integration.response.body.errorMessage`. + Per le integrazioni `HTTP` e `MOCK`, è `$integration.response.statuscode`. + Per `HTTP_PROXY` e `AWS_PROXY`, l'espressione non viene utilizzata poiché si richiede che il payload raggiunga il chiamante. # Configurare la mappatura dei dati per API WebSocket APIs Gateway La *mappatura dei dati* consente di mappare i dati da una [richiesta di instradamento](api-gateway-basic-concept.md#apigateway-definition-route-request) a un'integrazione back-end. **Nota** La mappatura dei dati per WebSocket APIs non è supportata in. Console di gestione AWSÈ necessario utilizzare AWS CLI AWS CloudFormation, o un SDK per configurare la mappatura dei dati. **Topics** + [Come mappare i dati di richiesta di instradamento ai parametri di richiesta di integrazione](#websocket-mapping-request-parameters) + [Esempi](#websocket-data-mapping-examples) ## Come mappare i dati di richiesta di instradamento ai parametri di richiesta di integrazione I parametri della richiesta di integrazione possono essere mappati da tutti i parametri di richiesta di instradamento definiti, dal corpo della richiesta [`context` o ](api-gateway-mapping-template-reference.md#context-variable-reference) dalle variabili [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) e dai valori statici. La tabella seguente mostra le espressioni di mappatura dei dati delle richieste di integrazione. Nella tabella *`PARAM_NAME`* è il nome del parametro di una richiesta di instradamento del tipo di parametro specifico. Deve corrispondere all'espressione regolare. `'^[a-zA-Z0-9._$-]+$]'` *JSONPath\$1EXPRESSION*è un' JSONPath espressione per un campo JSON del corpo della richiesta. | Origine dati mappata | Espressione di mappatura | | --- | --- | | Stringa di query di richiesta (supportata solo per l'instradamento \$1connect) | route.request.querystring.PARAM\$1NAME | | Intestazione della richiesta (supportata solo per l'instradamento \$1connect) | route.request.header.PARAM\$1NAME | | Stringa di query della richiesta a più valori (supportata solo per l'instradamento \$1connect) | route.request.multivaluequerystring.PARAM\$1NAME | | Intestazione della richiesta a più valori (supportata solo per l'instradamento \$1connect) | route.request.multivalueheader.PARAM\$1NAME | | Corpo di richiesta | route.request.body.JSONPath\$1EXPRESSION | | Variabili di fase | stageVariables.VARIABLE\$1NAME | | Variabili di contesto | context.VARIABLE\$1NAME che deve essere una delle [variabili di contesto supportate](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valore statico | 'STATIC\$1VALUE'. La STATIC\$1VALUE è una stringa letterale e deve essere racchiusa tra virgolette singole. | Quando crei una mappatura dei dati, AWS CLI assicurati di seguire il formato corretto per utilizzare i valori letterali con stringhe in. AWS CLI Per ulteriori informazioni, consulta [Using quotation marks and literals with strings in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) nella *Guida per l’utente di AWS Command Line Interface *. ## Esempi I seguenti AWS CLI esempi configurano le mappature dei dati. Per un CloudFormation modello di esempio, vedere. [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip) ### Mappare connectionId di un client a un'intestazione in una richiesta di integrazione Il comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) seguente mappa `connectionId` di un client a un’intestazione `connectionId` nella richiesta a un’integrazione backend. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### Mappatura di un parametro di stringa di query a un'intestazione in una richiesta di integrazione Il seguente esempio mappa un parametro della stringa di query `authToken` a un’intestazione `authToken` nella richiesta di integrazione. 1. Utilizza il seguente comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) per aggiungere il parametro della stringa di query `authToken` ai parametri della richiesta di instradamento. ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. Utilizza il seguente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) per mappare il parametro della stringa di query all’intestazione `authToken` nella richiesta di integrazione backend. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (Facoltativo) Se necessario, utilizzate quanto segue [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)per eliminare il parametro della stringa di `authToken` query dai parametri di richiesta del percorso. ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # WebSocket Riferimento al modello di mappatura delle API per API Gateway Questa sezione riassume l'insieme di variabili attualmente supportate WebSocket APIs in API Gateway. | Parametro | Descrizione | | --- | --- | | \$1context.connectionId | Un ID univoco per la connessione, che può essere utilizzato per effettuare un callback al client. | | \$1context.connectedAt | L'ora della connessione in formato [Epoch](https://en.wikipedia.org/wiki/Unix_time). | | \$1context.domainName | Un nome di dominio per l' WebSocket API. Può essere utilizzato per effettuare un callback al client (invece di un valore hardcoded). | | \$1context.eventType | Il tipo di evento: `CONNECT`, `MESSAGE` o `DISCONNECT`. | | \$1context.messageId | Un ID univoco sul lato server per un messaggio. Disponibile solo quando `$context.eventType` è `MESSAGE`. | | \$1context.routeKey | La chiave di instradamento selezionata. | | \$1context.requestId | Come `$context.extendedRequestId`. | | \$1context.extendedRequestId | Un ID generato automaticamente per la chiamata API, che contiene ulteriori informazioni utili per il debug/la risoluzione dei problemi. | | \$1context.apiId | Identificatore assegnato da API Gateway all'API. | | \$1context.authorizer.principalId | Identificazione dell'utente dell'entità principale associata al token inviato dal client e restituita da una funzione Lambda del provider di autorizzazioni Lambda di API Gateway (noto in precedenza come autorizzazioni ad hoc). | | \$1context.authorizer.property | Valore in formato stringa della coppia chiave/valore specificata della mappa `context` restituita da una funzione delle autorizzazioni Lambda di API Gateway. Ad esempio, se le autorizzazioni restituiscono la mappa `context` seguente: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
la chiamata di `$context.authorizer.key` restituisce la stringa `"value"`, la chiamata di `$context.authorizer.numKey` restituisce la stringa `"1"` e la chiamata di `$context.authorizer.boolKey` restituisce la stringa `"true"`. | | \$1context.error.messageString | Valore \$1context.error.message tra virgolette, ovvero "\$1context.error.message". | | \$1context.error.validationErrorString | Stringa contenente un messaggio dettagliato di errore di convalida. | | \$1context.identity.accountId | L'ID AWS dell'account associato alla richiesta. | | \$1context.identity.apiKey | Chiave del proprietario dell'API associata alla richiesta API abilitata dalla chiave. | | \$1context.identity.apiKeyId | ID chiave API associato alla richiesta API abilitata dalla chiave | | \$1context.identity.caller | Identificatore dell'entità principale del chiamante da cui proviene la richiesta. | | \$1context.identity.cognitoAuthenticationProvider | Un elenco separato da virgole con tutti i provider di autenticazione Amazon Cognito utilizzati dal chiamante che effettua la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. Ad esempio, per un'identità di un pool di utenti Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Per informazioni sui provider di autenticazione Amazon Cognito disponibili, consulta [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) nella *Guida per gli sviluppatori di Amazon Cognito*. | | \$1context.identity.cognitoAuthenticationType | Tipo di autenticazione Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. I valori possibili includono `authenticated` per le identità autenticate e `unauthenticated` per le identità non autenticate. | | \$1context.identity.cognitoIdentityId | ID identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | ID pool di identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. | | \$1context.identity.sourceIp | L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta all'endpoint di API Gateway. | | \$1context.identity.user | Identificatore dell'entità principale dell'utente da cui proviene la richiesta. | | \$1context.identity.userAgent | Agente utente della chiamata API. | | \$1context.identity.userArn | Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. | | \$1context.requestTime | Ora della richiesta in formato [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | L'ora della richiesta in formato [epoca (Unix epoch)](https://en.wikipedia.org/wiki/Unix_time) in millisecondi. | | \$1context.stage | Fase di distribuzione della chiamata API, ad esempio, beta o di produzione. | | \$1context.status | Lo stato della risposta. | | \$1input.body | Restituisce il payload non elaborato come stringa. | | \$1input.json(x) | Questa funzione valuta un' JSONPath espressione e restituisce i risultati come stringa JSON. Ad esempio, `$input.json('$.pets')` restituisce una stringa JSON che rappresenta la struttura di elementi "pet" (animali domestici). Per ulteriori informazioni su JSONPath, vedere [JSONPath](https://goessner.net/articles/JsonPath/)or [JSONPath for](https://github.com/json-path/JsonPath) Java. | | \$1input.path(x) | Accetta una stringa di JSONPath espressione (`x`) e restituisce una rappresentazione in oggetto JSON del risultato. In questo modo, puoi accedere agli elementi del payload e modificarli in modo nativo in [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Ad esempio, se l'espressione `$input.path('$.pets')` restituisce un oggetto in questo modo: 
[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]
`$input.path('$.pets').count()` restituisce `"3"`. Per ulteriori informazioni su JSONPath, vedere [JSONPath](http://goessner.net/articles/JsonPath/)or [JSONPath for Java](https://github.com/jayway/JsonPath). | | \$1stageVariables. | **rappresenta il nome di una variabile di fase. | | \$1stageVariables[''] | **rappresenta qualsiasi nome di variabile di fase. | | \$1\$1stageVariables['']\$1 | **rappresenta qualsiasi nome di variabile di fase. | | \$1util.escapeJavaScript() | Sfugge ai caratteri di una stringa utilizzando le regole delle JavaScript stringhe. Questa funzione trasforma qualsiasi virgoletta singola (`'`) in virgoletta preceduta da un carattere escape (`\'`). Tuttavia, le virgolette singole con escape non sono valide in JSON. Di conseguenza, quando l'output di questa funzione viene usato in una proprietà JSON, devi modificare di nuovo qualsiasi virgoletta singola con carattere escape (`\'`) in virgoletta singola normale (`'`). Questo viene mostrato nell'esempio seguente: 
 $util.escapeJavaScript(data).replaceAll("\\'","'")
| | \$1util.parseJson() | Da una stringa JSON restituisce una rappresentazione oggetto del risultato. Puoi usare il risultato di questa funzione per accedere agli elementi del payload e modificarli in modo nativo in Apache Velocity Template Language (VTL). Ad esempio, in presenza del payload seguente: 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
E se usi il modello di mappatura seguente: 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Otterrai l'output seguente: 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | Converte una stringa nel formato «application/x-www-form-urlencoded». | | \$1util.urlDecode() | Decodifica una stringa «application/». x-www-form-urlencoded | | \$1util.base64Encode() | Codifica i dati in una stringa con codifica base64. | | \$1util.base64Decode() | Decodifica i dati da una stringa con codifica base64. | # Tipi di supporti binari per API WebSocket in Gateway API Le API WebSocket API Gateway non supportano attualmente frame binari nei payload dei messaggi in entrata. Se un'app client invia un frame binario, viene rifiutato da API Gateway e la connessione al client viene annullata con codice 1003. Esiste una soluzione alternativa a questo comportamento. Se il client invia dati binari con codifica di testo (ad esempio, base64) come un frame di testo, puoi impostare la proprietà `contentHandlingStrategy` dell'integrazione su `CONVERT_TO_BINARY` per convertire il payload da stringa con codifica base64 in binario. Per restituire una risposta di instradamento per un payload binario in integrazioni non proxy, puoi impostare la proprietà `contentHandlingStrategy` della risposta di integrazione su `CONVERT_TO_TEXT` per convertire il payload da binario in stringa con codifica base64. # Invoca WebSocket APIs Dopo aver distribuito l' WebSocket API, le applicazioni client possono connettersi ad essa e inviarle messaggi, mentre il servizio di backend può inviare messaggi alle applicazioni client connesse: + Puoi utilizzarla `wscat` per connetterti alla tua WebSocket API e inviarle messaggi per simulare il comportamento del client. Per informazioni, consulta [Utilizzalo `wscat` per connetterti a un' WebSocket API e inviarle messaggi](apigateway-how-to-call-websocket-api-wscat.md). + Puoi utilizzare l'API @connections dal servizio di back-end per inviare un messaggio di callback a un client connesso, ottenere informazioni di connessione o scollegare il client. Per informazioni, consulta [Utilizzo di comandi `@connections` nel servizio di back-end](apigateway-how-to-call-websocket-api-connections.md). + Un'applicazione client può utilizzare la propria WebSocket libreria per richiamare l' WebSocketAPI. # Utilizzalo `wscat` per connetterti a un' WebSocket API e inviarle messaggi L'`[wscat](https://www.npmjs.com/package/wscat)`utilità è uno strumento utile per testare un' WebSocket API creata e distribuita in API Gateway. Puoi installare e utilizzare `wscat` nel modo seguente: 1. Scarica `wscat` da [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat). 1. Installa `wscat` eseguendo i comandi seguenti. ``` npm install -g wscat ``` 1. Per connetterti all'API, esegui il comando `wscat` come mostrato nell'esempio seguente. Questo esempio presuppone che l'impostazione `Authorization` sia `NONE`. ``` wscat -c wss://aabbccddee.execute-api.us-east-1.amazonaws.com/test/ ``` Sarà necessario sostituire `aabbccddee` con l'ID API effettivo, visualizzato nella console API Gateway o restituito dal comando [https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) della AWS CLI . Inoltre, se l'API si trova in una regione diversa da `us-east-1`, sarà necessario sostituire la regione corretta. 1. Per testare l'API, immetti un messaggio, ad esempio il seguente mentre sei connesso: ``` {"{jsonpath-expression}":"{route-key}"} ``` dove *\$1jsonpath-expression\$1* è un' JSONPathespressione ed *\$1route-key\$1* è una chiave di percorso per l'API. Esempio: ``` {"action":"action1"} {"message":"test response body"} ``` Per ulteriori informazioni su JSONPath, vedere [JSONPath](https://goessner.net/articles/JsonPath/)or [JSONPath for Java](https://github.com/json-path/JsonPath). 1. Per disconnetterti dall'API, immetti `ctrl-C`. # Utilizzo di comandi `@connections` nel servizio di back-end Il tuo servizio di backend può utilizzare le seguenti richieste HTTP di WebSocket connessione per inviare un messaggio di callback a un client connesso, ottenere informazioni sulla connessione o disconnettere il client. **Importante** Queste richieste utilizzano l’[autorizzazione IAM](apigateway-websocket-control-access-iam.md), pertanto occorre firmarle con [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Per eseguire questa operazione, puoi utilizzare l'API di gestione di API Gateway. Per ulteriori informazioni, consulta [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html). Nel comando seguente, è necessario sostituirlo `{api-id}` con l'ID API effettivo, che viene visualizzato nella console API Gateway o restituito dal comando AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html). È necessario stabilire la connessione prima di utilizzare questo comando. Per inviare un messaggio di callback al client, utilizza: ``` POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Puoi testare questa richiesta utilizzando `[Postman](https://www.postman.com/)` o chiamando `[awscurl](https://github.com/okigan/awscurl)` come nell'esempio seguente: ``` awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Il comando deve essere codificato tramite URL come nell'esempio seguente: ``` awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D ``` Per ottenere l'ultimo stato di connessione del client, utilizza: ``` GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Per scollegare il client, utilizza: ``` DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Puoi creare dinamicamente un URL di callback utilizzando le variabili `$context` nell'integrazione. Ad esempio, se si utilizza un'integrazione proxy Lambda con una funzione Lambda `Node.js`, puoi creare l'URL e inviare un messaggio a un client connesso come segue: ``` import { ApiGatewayManagementApiClient, PostToConnectionCommand, } from "@aws-sdk/client-apigatewaymanagementapi"; export const handler = async (event) => { const domain = event.requestContext.domainName; const stage = event.requestContext.stage; const connectionId = event.requestContext.connectionId; const callbackUrl = `https://${domain}/${stage}`; const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl }); const requestParams = { ConnectionId: connectionId, Data: "Hello!", }; const command = new PostToConnectionCommand(requestParams); try { await client.send(command); } catch (error) { console.log(error); } return { statusCode: 200, }; }; ``` Se utilizzi un nome di dominio personalizzato per l' WebSocket API, rimuovi la `stage` variabile dal codice della funzione. Quando si invia un messaggio di callback, la funzione Lambda deve disporre dell'autorizzazione per chiamare l'API di gestione di Gateway API. Se pubblichi un messaggio prima che venga stabilita la connessione o dopo la disconnessione del client, potresti ricevere un errore contenente `GoneException`.