` e valori statici.
Nel protocollo HTTP, in cui richieste e risposte vengono inviate in maniera sincrona, la comunicazione è essenzialmente unidirezionale. Nel WebSocket protocollo, la comunicazione è bidirezionale. Le risposte sono asincrone e non vengono necessariamente ricevute dal client nello stesso ordine di invio dei messaggi del client. Inoltre, il back-end può inviare messaggi al client.
**Nota**
Per una route configurata per utilizzare l'integrazione `AWS_PROXY` o `LAMBDA_PROXY`, la comunicazione è unidirezionale e API Gateway non trasferisce automaticamente la risposta del back-end alla risposta di instradamento. Ad esempio, in caso dell'integrazione `LAMBDA_PROXY`, il corpo restituito dalla funzione Lambda non verrà restituito al client. Se desideri che il client riceva risposte di integrazione, devi definire una risposta di instradamento per rendere possibile la comunicazione bidirezionale.
# WebSocket espressioni di selezione
API Gateway usa espressioni di selezione per valutare il contesto delle richieste e delle risposte e produrre una chiave. La chiave viene quindi utilizzata per selezionare da un set di valori possibili, in genere fornito da te, lo sviluppatore dell'API. L'esatto set di variabili supportate varierà a seconda del tipo di espressione. Ogni espressione viene descritta in modo dettagliato di seguito.
Per tutte le espressioni, il linguaggio segue lo stesso set di regole:
+ Una variabile ha il prefisso `"$"`.
+ Le parentesi graffe possono essere utilizzate per definire i limiti delle variabili in modo esplicito, ad esemp., `"${request.body.version}-beta"`.
+ Sono supportate numerose variabili, ma la valutazione viene eseguita una sola volta (non esiste la valutazione ricorsiva).
+ Il segno di dollaro (`$`) può essere preceduto dal carattere di escape `"\"`. Questa prassi è molto utile quando si definisce un'espressione associata alla chiave riservata `$default`, ad esempio `"\$default"`.
+ In alcuni casi, un formato di modello è obbligatorio. In questo caso, l'espressione deve essere racchiusa tra barre (`"/"`), ad esempio `"/2\d\d/"` per corrispondere ai codici di stato `2XX`.
**Topics**
+ [Espressioni di selezione della risposta di instradamento](#apigateway-websocket-api-route-response-selection-expressions)
+ [Espressioni di selezione della chiave API](#apigateway-websocket-api-apikey-selection-expressions)
+ [Espressioni di selezione della mappatura dell'API](#apigateway-websocket-api-mapping-selection-expressions)
+ [WebSocket riepilogo delle espressioni di selezione](#apigateway-websocket-api-selection-expression-table)
## Espressioni di selezione della risposta di instradamento
Una [risposta di instradamento](apigateway-websocket-api-route-response.md) viene utilizzata per modellare una risposta dal back-end al client. Infatti WebSocket APIs, una risposta di percorso è facoltativa. Una volta definito, segnala ad API Gateway che deve restituire una risposta a un client dopo aver ricevuto un WebSocket messaggio.
La valutazione dell'*espressione di selezione della risposta di instradamento* produce una chiave di risposta di instradamento. Infine, la chiave viene utilizzata per scegliere tra una delle [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html) associate all'API. Tuttavia, al momento è supportata solo la chiave `$default`.
## Espressioni di selezione della chiave API
Questa espressione viene valutata quando il servizio stabilisce che la richiesta specifica deve procedere solo se il client fornisce una [chiave API](api-gateway-basic-concept.md#apigateway-definition-api-key) valida.
Attualmente, i soli due valori supportati sono `$request.header.x-api-key` e `$context.authorizer.usageIdentifierKey`.
## Espressioni di selezione della mappatura dell'API
Questa espressione viene valutata per determinare quale fase API viene selezionata quando viene effettuata una richiesta utilizzando un dominio personalizzato.
Attualmente, l'unico valore supportato è `$request.basepath`.
## WebSocket riepilogo delle espressioni di selezione
La tabella seguente riassume i casi d'uso delle espressioni di selezione in WebSocket APIs:
| Espressione di selezione | Restituisce la chiave per | Note | Esempio di caso d'uso |
| --- | --- | --- | --- |
| Api.RouteSelectionExpression | Route.RouteKey | \$1defaultLa chiave è supportata come instradamento catch-all. | WebSocket Indirizza i messaggi in base al contesto della richiesta di un client. |
| Route.ModelSelectionExpression | Chiave per Route.RequestModels | Facoltativo. Se fornita per un'integrazione non proxy, viene effettuata la convalida del modello. `$default`La chiave è supportata come catch-all. | Convalida dinamica della richiesta all'interno dello stesso instradamento. |
| Integration.TemplateSelectionExpression | Chiave per Integration.RequestTemplates | Facoltativo. Può essere fornita per un'integrazione non proxy allo scopo di manipolare i payload in entrata. `${request.body.jsonPath}`Sono supportati e valori statici. `$default`La chiave è supportata come catch-all. | Manipolazione della richiesta dell'intermediario in base alle proprietà dinamiche della richiesta. |
| Integration.IntegrationResponseSelectionExpression | IntegrationResponse.IntegrationResponseKey | Facoltativo. Può essere fornita per un'integrazione non proxy. Agisce da corrispondenza di modello per i messaggi di errore (da Lambda) o i codici di stato (da integrazioni HTTP). `$default`È necessaria la chiave per far sì che le integrazioni non proxy agiscano da catch-all per le risposte con esito positivo. | Manipolazione della risposta del back-end. Scegliere l'azione da eseguire in base alla risposta dinamica del back-end, ad esempio la gestione distinta di determinati errori. |
| IntegrationResponse.TemplateSelectionExpression | Chiave per IntegrationResponse.ResponseTemplates | Facoltativo. Può essere fornita per un'integrazione non proxy. La chiave \$1default è supportata. | In alcuni casi, una proprietà dinamica della risposta potrebbe imporre trasformazioni differenti all'interno dello stesso instradamento e dell'integrazione associata. `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}`, Sono supportati , , , e valori statici. `$default`La chiave è supportata come catch-all. |
| Route.RouteResponseSelectionExpression | RouteResponse.RouteResponseKey | Dovrebbero essere forniti per avviare una comunicazione bidirezionale per un WebSocket percorso. Attualmente, questo valore è limitato solo a `$default`. | |
| RouteResponse.ModelSelectionExpression | Chiave per RouteResponse.RequestModels | Attualmente non è supportata. | |
# 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`.
# Pubblicazione di API WebSocket che i clienti possono invocare
La semplice creazione e sviluppo di un'API di API Gateway non la rende automaticamente richiamabile dagli utenti. Per renderla richiamabile, è necessario distribuire l'API in una fase. Inoltre, potrebbe essere necessario personalizzare l'URL che verrà utilizzato dagli utenti per accedere all'API. Puoi assegnarli un dominio che sia coerente con il tuo marchio o che sia più facile da ricordare dell'URL predefinito dell'API.
In questa sezione viene descritto come distribuire l'API e personalizzare l'URL fornito agli utenti per accedervi.
**Nota**
Per aumentare la sicurezza delle API API Gateway, il dominio `execute-api.{region}.amazonaws.com`è registrato nella [Public Suffix List (PSL)](https://publicsuffix.org/). Per una maggiore sicurezza, consigliamo di utilizzare i cookie con un prefisso `__Host-` se hai bisogno di impostare cookie sensibili nel nome di dominio predefinito per le API API Gateway. Questa pratica ti aiuterà a difendere il tuo dominio dai tentativi CSRF (cross-site request forgery). Per ulteriori informazioni, consulta la pagina [Impostazione cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) nella pagina Mozilla Developer Network.
**Topics**
+ [Crea fasi per WebSocket APIs API Gateway](websocket-api-stages.md)
+ [Implementazione WebSocket APIs in API Gateway](apigateway-set-up-websocket-deployment.md)
+ [Politica di sicurezza per WebSocket APIs API Gateway](websocket-api-ciphers.md)
+ [Nomi di dominio personalizzati per API WebSocket in Gateway API](websocket-api-custom-domain-names.md)
# Crea fasi per WebSocket APIs API Gateway
Una fase API è un riferimento logico a uno stato del ciclo di vita dell'API (ad esempio, `dev`, `prod`, `beta` o `v2`). Le fasi API sono identificate dal rispettivo ID API e dal nome della fase e sono incluse nell'URL utilizzato per richiamare l'API. Ogni fase è un riferimento con nome a una distribuzione dell'API e viene resa disponibile per le applicazioni client da chiamare.
Una distribuzione è uno snapshot della configurazione dell'API. Dopo essere stata distribuita a una fase, l'API è disponibile per i client da richiamare. È necessario distribuire un'API per attivare le modifiche apportate.
## Variabili di fase
Le variabili di fase sono coppie chiave-valore che puoi definire per una fase di un' WebSocket API. Fungono da variabili di ambiente e possono essere utilizzate nella configurazione dell'API.
Ad esempio, puoi definire una variabile di fase e quindi impostare il suo valore come un endpoint HTTP per un'integrazione proxy HTTP. Successivamente, puoi fare riferimento all'endpoint utilizzando il nome della variabile di fase associata. In questo modo, puoi utilizzare la stessa configurazione API con un endpoint diverso in ogni fase. Allo stesso modo, puoi utilizzare le variabili di fase per specificare un'integrazione di AWS Lambda funzioni diversa per ogni fase dell'API.
**Nota**
Le variabili di fase non sono destinate ad essere utilizzate per i dati sensibili, come le credenziali. Per trasferire dati sensibili alle integrazioni, usa un AWS Lambda autorizzatore. È possibile passare dati sensibili alle integrazioni nell'output del provider di autorizzazioni Lambda. Per ulteriori informazioni, consulta [Formato della risposta dell'autorizzazione](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
### Esempi
Per utilizzare una variabile di fase per personalizzare l'endpoint di integrazione HTTP, è necessario innanzitutto impostare il nome e il valore della variabile di fase (ad esempio `url`) con un valore pari a `example.com`. Quindi, impostare un'integrazione proxy HTTP. Anziché inserire l'URL dell'endpoint, è possibile comunicare ad API Gateway di usare il valore della variabile di fase, ossi, **http://\$1\$1stageVariables.url\$1**. Questo valore indica ad API Gateway di sostituire la variabile di fase `${}` al runtime, a seconda della fase dell'API.
È possibile fare riferimento alle variabili di fase in modo simile per specificare il nome di una funzione Lambda o un ruolo AWS ARN.
Quando si specifica un nome di funzione Lambda come valore della variabile di fase, è necessario configurare manualmente le autorizzazioni per la funzione Lambda. Il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) seguente aggiunge le autorizzazioni richieste:
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
## Riferimento alle variabili di fase di API Gateway
### Integrazione HTTP URIs
Puoi utilizzare una variabile di fase come parte di un URI di integrazione HTTP, come mostrato negli esempi seguenti.
+ Un URI completo senza protocoll – `http://${stageVariables.}`
+ Un dominio completo – `http://${stageVariables.}/resource/operation`
+ Un sottodominio – `http://${stageVariables.}.example.com/resource/operation`
+ Un percorso – `http://example.com/${stageVariables.}/bar`
+ Una stringa di query – `http://example.com/foo?q=${stageVariables.}`
### Funzioni Lambda
Puoi utilizzare una variabile di fase al posto di un nome di funzione o alias Lambda, come illustrato negli esempi seguenti.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Nota**
Per utilizzare una variabile di fase per una funzione Lambda, la funzione deve essere nello stesso account dell'API. Le variabili di fase non supportano le funzioni Lambda tra più account.
### AWS credenziali di integrazione
È possibile utilizzare una variabile stage come parte di un ARN di credenziali AWS utente o di ruolo, come illustrato nell'esempio seguente.
+ `arn:aws:iam:::${stageVariables.}`
# Implementazione WebSocket APIs in API Gateway
Dopo aver creato l' WebSocket API, devi distribuirla per renderla disponibile per essere richiamata dagli utenti.
Per distribuire un'API, crea una [distribuzione API](api-gateway-basic-concept.md#apigateway-definition-api-deployment) e associala a una [fase](api-gateway-basic-concept.md#apigateway-definition-api-stage). Ogni fase è una snapshot dell'API ed è resa disponibile per essere chiamata dalle app client.
**Importante**
Ogni volta che aggiorni un'API, devi ripeterne l'implementazione. Le modifiche a qualcosa di diverso dalle impostazioni di fase richiedono una nuova implementazione, incluse le modifiche alle seguenti risorse:
Percorsi
Integrazioni
Autorizzatori
C'è un limite predefinito di 10 fasi per API. Si consiglia di riutilizzare le fasi per le implementazioni.
Per chiamare un' WebSocket API distribuita, il client invia un messaggio all'URL dell'API. L'URL viene determinato dal nome host e dal nome fase dell'API.
**Nota**
API Gateway supporta payload fino a 128 KB con dimensione del frame massima di 32 KB. Se un messaggio supera i 32 KB, deve essere suddiviso in più frame, ciascuno di 32 KB o più piccolo.
Utilizzando il nome di dominio predefinito dell'API, l'URL di (ad esempio) un' WebSocket API in una determinata fase (`{stageName}`) ha il seguente formato:
```
wss://{api-id}.execute-api.{region}.amazonaws.com/{stageName}
```
Per rendere l'URL dell' WebSocket API più intuitivo, puoi creare un nome di dominio personalizzato (ad esempio,`api.example.com`) per sostituire il nome host predefinito dell'API. Il processo di configurazione è lo stesso di REST APIs. Per ulteriori informazioni, consulta [Nome di dominio personalizzato per REST pubblico APIs in API Gateway](how-to-custom-domains.md).
Le fasi permettono un efficace controllo delle versioni dell'API. Ad esempio, puoi distribuire un'API in una fase `test` e una fase `prod` e utilizzare la fase `test` come build di test e la fase `prod` come build stabile. Dopo che gli aggiornamenti hanno superato il test, puoi promuovere la fase `test` alla fase `prod`. La promozione può essere eseguita ridistribuendo l'API nella fase `prod`. Per ulteriori dettagli sulle fasi, consulta [Configurazione di una fase per una REST API in Gateway API](set-up-stages.md).
**Topics**
+ [Crea una distribuzione WebSocket API utilizzando il AWS CLI](#apigateway-create-websocket-deployment-using-awscli)
+ [Creare una distribuzione WebSocket API utilizzando la console API Gateway](#apigateway-create-websocket-deployment-using-console)
## Crea una distribuzione WebSocket API utilizzando il AWS CLI
Il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) crea l'implementazione:
```
aws apigatewayv2 --region us-east-1 create-deployment --api-id aabbccddee
```
L'output sarà simile al seguente:
```
{
"DeploymentId": "fedcba",
"DeploymentStatus": "DEPLOYED",
"CreatedDate": "2018-11-15T06:49:09Z"
}
```
L'API distribuita non può essere chiamata fino a quando non si associa la distribuzione a una fase. Puoi creare una nuova fase o riutilizzare una fase creata in precedenza.
Il comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-stage.html) seguente crea una nuova fase e la associa all’implementazione:
```
aws apigatewayv2 --region us-east-1 create-stage --api-id aabbccddee --deployment-id fedcba --stage-name test
```
L'output sarà simile al seguente:
```
{
"StageName": "test",
"CreatedDate": "2018-11-15T06:50:28Z",
"DeploymentId": "fedcba",
"DefaultRouteSettings": {
"MetricsEnabled": false,
"ThrottlingBurstLimit": 5000,
"DataTraceEnabled": false,
"ThrottlingRateLimit": 10000.0
},
"LastUpdatedDate": "2018-11-15T06:50:28Z",
"StageVariables": {},
"RouteSettings": {}
}
```
Puoi anche riutilizzare una fase esistente aggiornando la `deploymentId` proprietà della fase con l'ID di distribuzione appena creato (*deployment-id*). Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) seguente aggiorna l’ID di implementazione della fase:
```
aws apigatewayv2 update-stage --region region \
--api-id api-id \
--stage-name stage-name \
--deployment-id deployment-id
```
## Creare una distribuzione WebSocket API utilizzando la console API Gateway
Per utilizzare la console API Gateway per creare una distribuzione per un' WebSocket API:
1. Accedere alla console API Gateway e scegliere 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.
# Politica di sicurezza per WebSocket APIs API Gateway
API Gateway applica una politica di sicurezza `TLS_1_2` per tutti gli endpoint WebSocket API.
Una *policy di sicurezza* è una combinazione predefinita di una versione TLS minima e un pacchetto di crittografia offerta da Gateway Amazon API. Il protocollo TLS affronta i problemi di sicurezza della rete, ad esempio manomissioni e intercettazioni tra un client e un server. Quando i client stabiliscono un handshake TLS sull'API tramite il dominio personalizzato, la policy di sicurezza applica la versione di TLS e le opzioni del pacchetto di crittografia che i client possono scegliere di utilizzare. Questa policy di sicurezza accetta il traffico TLS 1.2 e TLS 1.3 e rifiuta il traffico TLS 1.0.
## Protocolli e cifrari TLS supportati per WebSocket APIs
La tabella seguente descrive i protocolli TLS supportati per. WebSocket APIs
| **Protocolli TLS** | **Policy di sicurezza TLS\$11\$12** |
| --- | --- |
| TLSv13. | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| TLSv12. | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
La tabella seguente descrive i codici TLS disponibili per la politica di sicurezza TLS 1\$12 per. WebSocket APIs
| **Crittografie TLS** | **Policy di sicurezza TLS\$11\$12** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| TLS\$1AES\$1256\$1GCM\$1 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| TLS\$1 \$1 CHACHA20 POLY1305 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECDSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDH-RSA- AES128 -GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECSA AES128 - - SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-RSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECDSA- -GCM AES256 - SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDH-RSA- AES256 -GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-ECSA AES256 - - SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| ECDHE-RSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/success_icon.svg) Sì |
## OpenSSL e nomi crittografia RFC
OpenSSL e IETF RFC 5246 utilizzano nomi diversi per le stesse crittografie. Per l'elenco dei nomi delle crittografie, consulta [OpenSSL e nomi crittografia RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names).
## Informazioni su REST APIs e HTTP APIs
Per ulteriori informazioni su REST APIs e HTTP APIs, vedere [Scegli una politica di sicurezza per il tuo dominio personalizzato in API Gateway](apigateway-custom-domain-tls-version.md) e[Politica di sicurezza per HTTP APIs in API Gateway](http-api-ciphers.md).
# Nomi di dominio personalizzati per API WebSocket in Gateway API
I *nomi di dominio personalizzati* sono URL più semplici e più intuitivi che è possibile fornire agli utenti delle API.
Dopo aver distribuito un'API, tu e i tuoi clienti potete richiamarla usando l'URL di base predefinito nel formato seguente:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
dove *api-id* è generato da Gateway API, *region* è la Regione AWS e *stage* è il valore che è stato specificato al momento dell'implementazione dell'API.
La parte del nome host dell'URL, `api-id.execute-api.region.amazonaws.com`, fa riferimento a un endpoint API. Il nome dell'endpoint API predefinito viene generato casualmente, è complesso da richiamare e non è intuitivo.
Con i nomi di dominio personalizzati, è possibile impostare il nome host dell'API e scegliere un percorso base (ad esempio `myservice`) per mappare l'URL alternativo all'API. Ad esempio, un URL di base dell'API più intuitivo può diventare:
```
https://api.example.com/myservice
```
## Considerazioni
Le seguenti considerazioni potrebbero influire sull'utilizzo di un nome di dominio personalizzato.
+ Se un nome di dominio personalizzato viene mappato a un'API WebSocket, non può essere mappato a una REST API o a un'API HTTP.
+ Sono supportati solo i nomi di dominio personalizzati regionali.
+ L'unica versione minima di TLS supportata è TLS 1.2.
+ È necessario creare o aggiornare il record di risorse del provider DNS per eseguire la mappatura all'endpoint API. In assenza di questa mappatura, le richieste API destinate al nome di dominio personalizzato non possono raggiungere API Gateway.
+ È possibile supportare un numero pressoché infinito di nomi di dominio senza superare la quota predefinita con un certificato jolly. Per ulteriori informazioni, consulta [Nomi di dominio personalizzati con caratteri jolly](http-api-custom-domain-names.md#http-wildcard-custom-domain-names).
## Prerequisiti
Di seguito sono riportati i prerequisiti per un nome di dominio personalizzato.
### Registrare un nome di dominio
Per configurare nomi di dominio personalizzati per le API, devi avere un nome di dominio Internet registrato. Puoi registrare un nome di dominio Internet utilizzando [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) oppure un registrar di dominio di terze parti a tua scelta. Il nome di dominio personalizzato può essere il nome di un sottodominio o del dominio root (detto anche "apex di zona") di un dominio Internet registrato.
Il nome di dominio deve seguire la specifica [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) e può avere un massimo di 63 ottetti per etichetta e 255 ottetti in totale.
### Certificati per nomi di dominio personalizzati
Prima di configurare un nome di dominio personalizzato per un'API, è necessario che sia già presente un certificato SSL/TLS in ACM. Se ACM non è disponibile nella Regione AWS in cui si sta creando il nome di dominio personalizzato, è necessario importare nella Regione un certificato in Gateway API.
Per importare un certificato SSL/TLS, devi fornire il corpo del certificato SSL/TLS in formato PEM, la sua chiave privata e la catena di certificati per il nome di dominio personalizzato.
Ogni certificato archiviato in ACM è identificato dal relativo ARN. Con i certificati emessi da ACM, non devi preoccuparti di esporre dettagli sensibili del certificato, come la chiave privata. Per usare un certificato gestito da AWS per un nome di dominio, devi semplicemente fare riferimento al relativo ARN.
Se l’applicazione utilizza il blocco dei certificati, talvolta denominato associazione SSL, per associare un certificato ACM, è possibile che l'applicazione non riesca a connettersi al tuo dominio dopo che AWS ha rinnovato il certificato. Per ulteriori informazioni, consulta [Probemi nel blocco dei certificati](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) nella *Guida per l'utente di AWS Certificate Manager*.
## Nomi di dominio personalizzati con caratteri jolly
Con i nomi di dominio personalizzati con caratteri jolly, è possibile supportare un numero quasi infinito di nomi di dominio senza superare la [quota predefinita](limits.md). Ad esempio, è possibile dare a ciascuno dei clienti il proprio nome di dominio, `customername.api.example.com`.
Per creare un nome di dominio personalizzato con caratteri jolly, specificare un carattere jolly (`*`) come primo sottodominio di un dominio personalizzato che rappresenta tutti i possibili sottodomini di un dominio radice.
Ad esempio, il nome di dominio personalizzato con caratteri jolly `*.example.com` genera sottodomini quali `a.example.com`, `b.example.com` e `c.example.com`, indirizzati tutti allo stesso dominio.
I nomi di dominio personalizzati con caratteri jolly supportano configurazioni distinte dai nomi di dominio personalizzati standard di API Gateway. Ad esempio, in un singolo account AWS, è possibile configurare `*.example.com` e `a.example.com` affinché si comportino in modo diverso.
È possibile utilizzare le variabili di contesto `$context.domainName` e `$context.domainPrefix` per determinare il nome di dominio utilizzato da un client per chiamare l'API. Per ulteriori informazioni sulle variabili di contesto, consulta [Variabili per le trasformazioni dei dati per Gateway API](api-gateway-mapping-template-reference.md).
Per creare un nome di dominio personalizzato con caratteri jolly, è necessario fornire un certificato emesso da ACM che sia stato convalidato utilizzando il DNS o il metodo di convalida della posta elettronica.
**Nota**
Non è possibile creare un nome di dominio personalizzato con caratteri jolly se un account AWS diverso ha creato un nome di dominio personalizzato in conflitto con il nome di dominio personalizzato con caratteri jolly. Ad esempio, se l'account A ha creato `a.example.com`, l'account B non può creare il nome di dominio personalizzato con caratteri jolly `*.example.com`.
Se l'account A e l'account B condividono un proprietario, è possibile contattare il [Centro assistenza AWS](https://console.aws.amazon.com/support/home#/) per richiedere un'eccezione.
## Passaggi successivi per nomi di dominio personalizzati
Per configurare un nome di dominio personalizzato per un'API HTTP, consulta la documentazione disponibile nella sezione REST API della Guida per gli sviluppatori di Gateway API.
Per prima cosa, si specifica un certificato per il nome di dominio personalizzato. Per ulteriori informazioni, consulta [Prepara i certificati in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Successivamente, si crea un nome di dominio personalizzato regionale. Per ulteriori informazioni, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
# Mappatura delle fasi API a un nome di dominio personalizzato per le API WebSocket
È possibile utilizzare le mappature API per connettere le fasi API a un nome di dominio personalizzato. Dopo aver creato un nome di dominio e aver configurato i record DNS, è possibile utilizzare le mappature API per inviare il traffico alle API tramite il nome di dominio personalizzato.
Una mappatura API specifica un'API, una fase e, facoltativamente, un percorso da utilizzare per la mappatura. Ad esempio, è possibile mappare la fase `production` di un'API su `wss://api.example.com/orders`.
Prima di creare una mappatura API, è necessario disporre di un'API, di una fase e di un nome di dominio personalizzato. Per ulteriori informazioni sulla creazione di un nome di dominio personalizzato, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
## Restrizioni
+ In una mappatura API, il nome di dominio personalizzato e le API mappate devono trovarsi nello stesso account AWS.
+ Le mappature API devono contenere solo lettere, numeri e i seguenti caratteri: `$-_.+!*'()`.
+ La lunghezza massima per il percorso in una mappatura API è di 300 caratteri.
+ Non è possibile mappare le API WebSocket allo stesso nome di dominio personalizzato di un'API HTTP o un'API REST.
+ Se si crea una mappatura API con più livelli, Gateway API converte tutti i nomi di intestazione in lettere minuscole.
## Creare una mappatura API
Per creare una mappatura API, innanzitutto è necessario creare un nome di dominio personalizzato, un'API e una fase. Per informazioni sulla creazione di un nome di dominio personalizzato, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md).
------
#### [ Console di gestione AWS ]
**Per creare una mappatura API**
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere **Nomi di dominio personalizzati**.
1. Selezionare un nome di dominio personalizzato già creato.
1. Scegliere **API mappings (mappature API)**.
1. Scegliere **Configure API mappings (Configura mappature API)**.
1. Scegliere **Add new mapping (Aggiungi nuova mappatura)**.
1. Immettere un'**API**, uno **Stage (Fase)**e, facoltativamente, un **Path (Percorso)**.
1. Selezionare **Salva**.
------
#### [ AWS CLI ]
Il comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) seguente crea una mappatura API. In questo esempio, API Gateway invia le richieste `api.example.com/v1` all'API e alla fase specificate.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1 \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
Il seguente esempio di CloudFormation consente di creare una mappatura API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'v1'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Tipi di indirizzo IP per nomi di dominio personalizzati per API WebSocket
Quando si crea un nome di dominio personalizzato, è possibile specificare il tipo di indirizzo IP che può invocare il dominio. È possibile scegliere IPv4 per risolvere gli indirizzi IPv4 per invocare il dominio oppure dualstack per consentire a entrambi gli indirizzi IPv4 e IPv6 di invocare il dominio. È 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 i nomi di dominio personalizzati di Gateway API è IPv4.
+ Per il nome di dominio personalizzato, non è necessario che tutte le API mappate ad esso abbiano lo stesso tipo di indirizzo IP. 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 del nome di dominio personalizzato
È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell’endpoint del nome di dominio. È possibile aggiornare la configurazione dell’endpoint utilizzando la Console di gestione AWS, AWS CLI, CloudFormation o un AWS SDK.
------
#### [ Console di gestione AWS ]
**Per modificare il tipo di indirizzo IP di un nome di dominio personalizzato**
1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Scegliere un nome di dominio personalizzato pubblico.
1. Scegliere **Configurazione endpoint**.
1. Per Tipo di indirizzo IP, selezionare **IPv4** o **Dualstack**.
1. Selezionare **Salva**.
------
#### [ AWS CLI ]
Il comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) seguente aggiorna un’API in modo che abbia un tipo di indirizzo IP dualstack:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
L'output sarà simile al seguente:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Disabilita l'endpoint predefinito per WebSocket APIs
Per impostazione predefinita, i client possono richiamare l'API utilizzando l'endpoint `execute-api` generato da API Gateway per l'API. Per garantire che i client possano accedere all'API solo utilizzando un nome di dominio personalizzato con l'autenticazione TLS reciproca, disattivare l'endpoint `execute-api` predefinito. Quando si disattiva l'endpoint predefinito, questa operazione influisce su tutte le fasi di un'API.
La procedura seguente mostra come disabilitare l'endpoint predefinito per un' WebSocket API.
------
#### [ Console di gestione AWS ]
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. Scegli **Impostazioni API**.
1. In **Dettagli API** seleziona **Modifica**.
1. Per **Endpoint predefinito** seleziona **Inattivo**.
1. Scegli **Save changes** (Salva modifiche).
1. Nel pannello di navigazione principale scegli **Instradamenti**.
1. Scegli **Distribuzione**, quindi implementa nuovamente l'API o crea una nuova fase per rendere effettiva la modifica.
------
#### [ AWS CLI ]
Il seguente comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) disabilita l'endpoint predefinito per un'API: WebSocket
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Dopo aver disabilitato l'endpoint predefinito, è necessario distribuire l'API per rendere effettiva la modifica.
Il AWS CLI comando seguente crea una distribuzione.
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Proteggi il tuo WebSocket APIs API Gateway
API Gateway fornisce diversi modi per proteggere l'API da determinate minacce, ad esempio utenti malintenzionati o picchi di traffico. È possibile proteggere l’API usando strategie come la generazione di certificati SSL o l’impostazione degli obiettivi della limitazione (della larghezza di banda della rete). Per ulteriori informazioni sulla generazione dei certificati SSL, consultare [Generazione e configurazione di un certificato SSL per l'autenticazione backend in Gateway API](getting-started-client-side-ssl-authentication.md). Gli obiettivi della limitazione (della larghezza di banda della rete) sono descritti in dettaglio nella parte restante di questa sezione.
Puoi configurare la limitazione per le tue per APIs evitare che vengano sopraffatte da troppe richieste. Le limitazioni della larghezza di banda della rete sono applicate sulla base del massimo sforzo e dovrebbero essere considerate come obiettivi e non limiti massimi garantiti delle richieste.
API Gateway limita la larghezza di banda della rete delle richieste nell'API mediante l'algoritmo di token bucket, dove un token rappresenta una richiesta. In particolare, API Gateway esamina la frequenza e il numero di richieste inviate rispetto APIs a tutti gli utenti del tuo account, per regione. Nell'algoritmo di bucket token, un picco può consentire il superamento predefinito di tali limiti, ma anche altri fattori possono causare il superamento dei limiti in alcuni casi.
Quando le richieste inviate superano i limiti impostati per il tasso a regime e per i limiti di picco, API Gateway inizia a limitare le richieste. I clienti potrebbero ricevere risposte agli errori `429 Too Many Requests` a questo punto. Quando rileva queste eccezioni, il client può reinviare le richieste non riuscite in modo da limitare la velocità.
In qualità di sviluppatore di API, puoi impostare i limiti target per le singole fasi o percorsi dell'API per migliorare le prestazioni complessive di tutto APIs il tuo account.
## Limitazione a livello di account per regione
Per impostazione predefinita, API Gateway limita le richieste allo stato stazionario (RPS) APIs all'interno di un AWS account, per regione. Inoltre, limita il burst (ovvero la dimensione massima del bucket) per tutti gli elementi di un account, per regione APIs . AWS In API Gateway, il limite dei picchi rappresenta il numero massimo di invii di richieste che API Gateway può gestire prima di restituire risposte di errore `429 Too Many Requests`. Per ulteriori informazioni sulla limitazione delle quote, vedere [Quote Gateway Amazon API](limits.md).
I limiti per account vengono applicati a tutti i membri di un account APIs in una regione specificata. Il limite di tariffa a livello di account può essere aumentato su richiesta: sono possibili limiti più elevati con APIs timeout più brevi e carichi utili inferiori. Per richiedere un aumento dei limiti di limitazione a livello di account per Regione, contatta il [Centro assistenza AWS](https://console.aws.amazon.com/support/home#/). Per ulteriori informazioni, consulta [Quote Gateway Amazon API](limits.md). Tieni presente che questi limiti non possono essere superiori ai limiti di limitazione. AWS
## Throttling a livello di instradamento
Puoi impostare il throttling a livello di route per sostituire i limiti di throttling delle richieste a livello di account per una fase specifica o per singoli route nell'API. I limiti della limitazione (della larghezza di banda della rete) della route di default non possono superare i limiti di velocità a livello di account.
È possibile configurare la limitazione a livello di percorso utilizzando AWS CLI. Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) seguente configura la limitazione (della larghezza di banda della rete) personalizzata per la fase e l’instradamento specificati di un’API:
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"messages":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Monitoraggio delle API WebSocket in Gateway API
Puoi utilizzare i parametri CloudWatch e CloudWatch Logs per monitorare le API WebSocket. Combinando log e parametri, puoi registrare gli errori e monitorare le prestazioni dell'API.
**Nota**
L'API Gateway potrebbe non generare log e parametri nei seguenti casi:
Errori 413 per richiesta troppo grande
Errori 429 per troppe richieste
Errori serie 400 per richieste inviate a un dominio personalizzato che non dispone del mapping API
Errori serie 500 per malfunzionamenti interni
**Topics**
+ [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md)
+ [Configurazione della registrazione per API WebSocket APIs Gateway](websocket-api-logging.md)
# Monitora l'esecuzione delle WebSocket API con CloudWatch metriche
Puoi utilizzare i CloudWatch parametri di [Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) per monitorare WebSocket APIs. La configurazione è simile a quella utilizzata per REST APIs. Per ulteriori informazioni, consulta [Monitora l'esecuzione delle API REST con i CloudWatch parametri di Amazon](monitoring-cloudwatch.md).
Le seguenti metriche sono supportate per WebSocket APIs:
| Metrica | Description |
| --- | --- |
| ConnectCount | Il numero di messaggi inviati all'integrazione route \$1connect. |
| MessageCount | Il numero di messaggi inviati all' WebSocket API, da o verso il client. |
| IntegrationError | Il numero di richieste che restituiscono una risposta 4XX/5XX dall'integrazione. |
| ClientError | Il numero di richieste con una risposta 4XX restituita da API Gateway prima che l'integrazione venga richiamata. |
| ExecutionError | Errori che si sono verificati durante la chiamata all'integrazione. |
| IntegrationLatency | La differenza di tempo tra API Gateway che invia la richiesta all'integrazione e API Gateway che riceve la risposta dall'integrazione. Soppresso per callback e integrazioni fittizie. |
Per filtrare i parametri di API Gateway, puoi utilizzare le dimensioni nella seguente tabella.
| Dimensione | Description |
| --- | --- |
| ApiId | Filtra i parametri API Gateway per un'API con l'ID API specificato. |
| ApiId, Fase | Filtra i parametri API Gateway per una fase API con l'ID API e l'ID fase specificati. |
| ApiId, Metodo, Risorsa, Fase | Filtra le metriche di Gateway API per un metodo API con l'ID API, l'ID fase, il percorso della risorsa e l'ID instradamento specificati. API Gateway non invierà queste metriche a meno che tu non abbia abilitato esplicitamente le metriche dettagliate CloudWatch . È possibile farlo richiamando l'[UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html)azione dell'API REST API Gateway V2 a cui aggiornare la `detailedMetricsEnabled` proprietà. `true` In alternativa, puoi chiamare il AWS CLI comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) per aggiornare la `DetailedMetricsEnabled` proprietà a. `true` L'abilitazione di tali parametri comporta addebiti aggiuntivi sul tuo account. Per informazioni sui prezzi, consulta la pagina [ CloudWatchdei prezzi di Amazon](https://aws.amazon.com/cloudwatch/pricing/). |
# Configurazione della registrazione per API WebSocket APIs Gateway
È possibile abilitare la registrazione per scrivere i log nei registri. CloudWatch Esistono due tipi di accesso tramite API CloudWatch: registrazione dell'esecuzione e registrazione degli accessi. Nella registrazione dell'esecuzione, API Gateway gestisce i CloudWatch log. Il processo include la creazione di gruppi e flussi di log e la segnalazione ai flussi di log delle richieste e delle risposte dell'intermediario.
Per migliorare il livello di sicurezza, è consigliabile utilizzare la registrazione nei log dell’esecuzione a livello di `ERROR` o `INFO`. 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 *.
Nella registrazione degli accessi, in qualità di sviluppatore dell'API puoi registrare chi ha avuto accesso alla tua API e in che modo l'intermediario ha avuto accesso all'API. Puoi creare un gruppo di log personalizzato o sceglierne uno esistente che potrebbe essere gestito da API Gateway. Per specificare i dettagli di accesso, seleziona variabili `$context` (espresse in un formato a scelta) e scegli un gruppo di log come destinazione.
Per istruzioni su come configurare la CloudWatch registrazione, consulta. [Configurare la registrazione delle CloudWatch API utilizzando la console API Gateway](set-up-logging.md#set-up-access-logging-using-console)
Quando specifichi il **Log Format (Formato di log)**, puoi scegliere quali variabili di contesto registrare. Sono supportate le seguenti variabili.
| Parametro | Descrizione |
| --- | --- |
| \$1context.apiId | Identificatore assegnato da API Gateway all'API. |
| \$1context.authorize.error | Il messaggio di errore di autorizzazione. |
| \$1context.authorize.latency | La latenza di autorizzazione in ms. |
| \$1context.authorize.status | Il codice di stato restituito da un tentativo di autorizzazione. |
| \$1context.authorizer.error | Il messaggio di errore restituito da un'autorizzazione. |
| \$1context.authorizer.integrationLatency | La latenza del provider di autorizzazioni Lambda in ms. |
| \$1context.authorizer.integrationStatus | Il codice di stato restituito da un'autorizzazione Lambda. |
| \$1context.authorizer.latency | La latenza di autorizzazione in ms. |
| \$1context.authorizer.requestId | L'ID della richiesta dell' AWS endpoint. |
| \$1context.authorizer.status | Il codice di stato restituito da un'autorizzazione. |
| \$1context.authorizer.principalId | Identificazione dell'utente principale associata al token inviato dal client e restituita da una funzione Lambda del provider di autorizzazioni di Lambda API Gateway. (Un provider di autorizzazioni Lambda in precedenza noto 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.authenticate.error | Il messaggio di errore restituito da un tentativo di autenticazione. |
| \$1context.authenticate.latency | La latenza di autenticazione in ms. |
| \$1context.authenticate.status | Il codice di stato restituito da un tentativo di autenticazione. |
| \$1context.connectedAt | L'ora della connessione in formato [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.connectionId | Un ID univoco per la connessione, che può essere utilizzato per effettuare un callback al client. |
| \$1context.domainName | Un nome di dominio per l' WebSocket API. Può essere utilizzato per effettuare un callback al client (invece di un valore codificato). |
| \$1context.error.message | Una stringa contenente un messaggio di errore API Gateway. |
| \$1context.error.messageString | Valore \$1context.error.message tra virgolette, ovvero "\$1context.error.message". |
| \$1context.error.responseType | Il tipo di risposta di errore. |
| \$1context.error.validationErrorString | Stringa contenente un messaggio di errore di convalida dettagliato. |
| \$1context.eventType | Il tipo di evento: `CONNECT`, `MESSAGE` o `DISCONNECT`. |
| \$1context.extendedRequestId | Equivalente a \$1context.requestId. |
| \$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 dell'intermediario che ha firmato la richiesta. Supportato per route che utilizzano l'autorizzazione IAM. |
| \$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.principalOrgId | L'[ID organizzazione AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Supportato per route che utilizzano l'autorizzazione IAM. |
| \$1context.identity.sourceIp | Indirizzo IP di origine della connessione TCP da cui proviene la richiesta ad API Gateway. |
| \$1context.identity.user | Identificatore dell'entità principale dell'utente che sarà autorizzato per l'accesso alle risorse. Supportato per route che utilizzano l'autorizzazione IAM. |
| \$1context.identity.userAgent | Agente utente del chiamante API. |
| \$1context.identity.userArn | Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. |
| \$1context.integration.error | Il messaggio di errore restituito da un'integrazione. |
| \$1context.integration.integrationStatus | Per l'integrazione del proxy Lambda, il codice di stato restituito dal codice della funzione Lambda di backend AWS Lambda, non dal codice della funzione Lambda. |
| \$1context.integration.latency | Latenza di integrazione in ms. Equivalente a \$1context.integrationLatency. |
| \$1context.integration.requestId | L'ID della AWS richiesta dell'endpoint. Equivalente a \$1context.awsEndpointRequestId. |
| \$1context.integration.status | Il codice di stato restituito da un'integrazione. Per le integrazioni proxy Lambda, questo è il codice di stato restituito dal codice della funzione Lambda. Equivalente a \$1context.integrationStatus. |
| \$1context.integrationLatency | La latenza di integrazione in millisecondi, disponibile solo per il log di accesso. |
| \$1context.messageId | Un ID univoco sul lato server per un messaggio. Disponibile solo quando `$context.eventType` è `MESSAGE`. |
| \$1context.requestId | Come `$context.extendedRequestId`. |
| \$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.routeKey | La chiave di instradamento selezionata. |
| \$1context.stage | Fase di distribuzione della chiamata API, ad esempio, beta o di produzione. |
| \$1context.status | Lo stato della risposta. |
| \$1context.waf.error | Il messaggio di errore restituito da AWS WAF. |
| \$1context.waf.latency | La AWS WAF latenza in ms. |
| \$1context.waf.status | Il codice di stato restituito da AWS WAF. |
Esempi di alcuni formati di log delle operazioni di accesso utilizzati con maggiore frequenza sono mostrati nella console API Gateway ed elencati qui di seguito.
+ `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId
```
I caratteri di continuazione (`\`) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (`\n`) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.
+ `JSON`:
```
{
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}
```
I caratteri di continuazione (`\`) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (`\n`) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.
+ `XML`:
```
\
$context.identity.sourceIp \
$context.identity.caller \
$context.identity.user \
$context.requestTime \
$context.eventType \
$context.routeKey \
$context.status \
$context.connectionId \
```
I caratteri di continuazione (`\`) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (`\n`) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.
+ `CSV` (valori separati da virgola):
```
$context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId
```
I caratteri di continuazione (`\`) sono intesi come un aiuto visivo. Il formato del registro deve essere una singola riga. È possibile aggiungere un carattere di nuova riga (`\n`) alla fine del formato di registro per includere una nuova riga alla fine di ogni voce di registro.