Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Tutorial: creare un' WebSocket API con un' AWS integrazione
<a name="websocket-api-step-functions-tutorial"></a>

In questo tutorial, crei un'applicazione di trasmissione serverless con un' WebSocket API. I client possono ricevere messaggi senza dover eseguire il polling per gli aggiornamenti.

 Questo tutorial mostra come trasmettere messaggi ai client connessi e include un esempio di sistema di autorizzazione Lambda, un'integrazione fittizia e un'integrazione non proxy con Step Functions.

![Panoramica dell'architettura dell'API creata in questo tutorial.](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/ws-sfn-app.png)


Dopo aver creato le risorse utilizzando un CloudFormation modello, utilizzerai la console API Gateway per creare un' WebSocket API che si integri con AWS le tue risorse. Allegherai un autorizzatore Lambda alla tua API e creerai un'integrazione di AWS servizi con Step Functions per avviare l'esecuzione di una macchina a stati. La macchina a stati Step Functions invocherà una funzione Lambda che invia un messaggio a tutti i client connessi.

Dopo aver creato l'API, testerai la connessione all'API e verificherai che i messaggi vengano inviati e ricevuti. Il completamento di questo tutorial richiede circa 45 minuti.

**Topics**
+ [Prerequisiti](#websocket-api-step-functions-prerequisites)
+ [Fase 1: Creazione delle risorse](#websocket-api-step-functions-create-dependencies)
+ [Fase 2: Creare un'API WebSocket](#websocket-api-step-functions-create-api)
+ [Passaggio 3: creare un sistema di autorizzazione Lambda](#websocket-api-step-functions-create-authorizer)
+ [Passaggio 4: creare un'integrazione bidirezionale fittizia](#websocket-api-step-functions-create-mock-integration)
+ [Passaggio 5: creare un'integrazione non proxy con Step Functions](#websocket-api-step-functions-create-step-function-integration)
+ [Fase 6: Test dell'API](#websocket-api-step-functions-test-api)
+ [Fase 7: pulire](#websocket-api-step-functions-cleanup)
+ [Passaggi successivi](#websocket-api-step-functions-next-steps)

## Prerequisiti
<a name="websocket-api-step-functions-prerequisites"></a>

Sono necessari i seguenti prerequisiti:
+ Un AWS account e un AWS Identity and Access Management utente con accesso alla console. Per ulteriori informazioni, consulta [Configurazione per l'utilizzo di Gateway API](setting-up.md).
+ `wscat` per la connessione all'API. Per ulteriori informazioni, consulta [Utilizzalo `wscat` per connetterti a un' WebSocket API e inviarle messaggi](apigateway-how-to-call-websocket-api-wscat.md).

Ti consigliamo di completare il tutorial dell'app di WebSocket chat prima di iniziare questo tutorial. Per completare il tutorial sull'app di WebSocket chat, consulta[Tutorial: crea un'app di WebSocket chat con WebSocket API, Lambda e DynamoDB](websocket-api-chat-app.md).

## Fase 1: Creazione delle risorse
<a name="websocket-api-step-functions-create-dependencies"></a>

Scarica e decomprimi [il modello di creazione dell'app per CloudFormation](samples/ws-sfn-starter.zip). Userai questo modello per creare quanto segue:
+ Funzioni Lambda che gestiscono le richieste API e autorizzano l'accesso alla tua API.
+ Una tabella DynamoDB per memorizzare l'identificazione IDs del client e dell'utente principale restituita dall'autorizzatore Lambda.
+ Una macchina a stati Step Functions per inviare messaggi ai client connessi.

**Per creare uno stack CloudFormation**

1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)

1. Scegliere **Create stack (Crea stack)**, quindi **With new resources (standard) (Con nuove risorse (standard))**.

1. In **Specificare modello**, scegliere **Carica un file modello**.

1. Selezionare il modello scaricato.

1. Scegli **Next (Successivo)**. 

1. Per **Stack name (Nome stack)**, inserire **websocket-step-functions-tutorial**, quindi scegliere **Next (Avanti)**.

1. Per **Configure stack options (Configura opzioni di stack)**, scegliere **Next (Successivo)**.

1. Per quanto riguarda **le funzionalità**, riconosci che CloudFormation puoi creare risorse IAM nel tuo account.

1. Scegli **Avanti**, quindi scegli **Invia**.

CloudFormation fornisce le risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Scegli la scheda **Output** per vedere le risorse create e le relative. ARNs Quando lo stato del tuo CloudFormation stack è **CREATE\_COMPLETE**, sei pronto per passare alla fase successiva.

## Fase 2: Creare un'API WebSocket
<a name="websocket-api-step-functions-create-api"></a>

Creerai un' WebSocket API per gestire le connessioni dei client e indirizzare le richieste verso le risorse che hai creato nel passaggio 1.

**Per creare un' WebSocket API**

1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)

1. Seleziona **Create API** (Crea API). **Quindi, per **WebSocket API**, scegli Build.**

1. Per **API name (Nome API)**, immettere **websocket-step-functions-tutorial**.

1. Per il **tipo di indirizzo IP**, seleziona **IPv4**.

1. Per **Route selection expression** (Espressione di selezione routing), inserire **request.body.action**.

   L'espressione di selezione del routing determina quale routing viene richiamato da API Gateway quando un client invia un messaggio.

1. Scegli **Next (Successivo)**.

1. Per **Instradamenti predefiniti**, scegli **Aggiungi $connect**, **Aggiungi $disconnect** e **Aggiungi $default**.

   Gli instradamenti **$connect** e **$disconnect** sono instradamenti speciali che Gateway API richiama automaticamente quando un client si connette o si disconnette da un'API. Gateway API invoca l'instradamento **$default** quando non ci sono altri instradamenti corrispondenti a una richiesta. Creerai un percorso personalizzato per connetterti a Step Functions dopo aver creato l'API.

1. Seleziona **Successivo**.

1. Per **Integrazione per $connect**, procedi come segue:

   1. Per **Tipo di integrazione**, scegli **Lambda**.

   1. Per la **funzione Lambda**, scegli la funzione **$connect** Lambda corrispondente che hai creato CloudFormation nel passaggio 1. Il nome della funzione Lambda deve iniziare con **websocket-step**.

1. Per **Integrazione per $disconnect**, procedi come segue:

   1. Per **Tipo di integrazione**, scegli **Lambda**.

   1. Per la funzione **Lambda, scegli la funzione** Lambda **$disconnect** corrispondente che hai creato nel passaggio 1. CloudFormation Il nome della funzione Lambda deve iniziare con **websocket-step**.

1. Per **Integrazione per $default**, scegli **mock**.

   In un'integrazione fittizia, Gateway API gestisce la risposta di instradamento senza un backend di integrazione.

1. Scegli **Next (Successivo)**.

1. Esamina la fase creata da API Gateway. Di default, Gateway API crea una fase denominata **production** e implementa automaticamente l'API in quella fase. Scegli **Next (Successivo)**.

1. Scegliere **Create and deploy** (Crea e implementa).

## Passaggio 3: creare un sistema di autorizzazione Lambda
<a name="websocket-api-step-functions-create-authorizer"></a>

Per controllare l'accesso alla tua WebSocket API, crei un autorizzatore Lambda. Il CloudFormation modello ha creato la funzione di autorizzazione Lambda per te. La funzione Lambda è visibile nella console Lambda. Il nome deve iniziare con **websocket-step-functions-tutorial-AuthorizerHandler**. Questa funzione Lambda nega tutte le chiamate all' WebSocket API a meno che l'intestazione non lo `Authorization` sia. `Allow` La funzione Lambda passa anche la variabile `$context.authorizer.principalId` all'API, che viene utilizzata successivamente nella tabella DynamoDB per identificare i chiamanti dell'API.

In questo passaggio configurerai l'instradamento **$connect** per utilizzare il sistema di autorizzazione Lambda.

**Per creare un sistema di autorizzazione Lambda**

1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)

1. Nel riquadro di navigazione principale, scegli **Autorizzazioni**.

1. Scegli **Crea provider di autorizzazioni**.

1. Per **Nome del provider di autorizzazioni**, inserisci **LambdaAuthorizer**.

1. Per **Authorizer ARN**, immettere il nome dell'autorizzatore creato dal modello. CloudFormation Il nome deve iniziare con **websocket-step-functions-tutorial-AuthorizerHandler**.
**Nota**  
Ti consigliamo di non utilizzare questo autorizzatore di esempio per la tua produzione. APIs

1. Per **Tipo di origine identità**, scegli **Intestazione**. In **Chiave**, inserire **Authorization**.

1. Scegli **Crea autorizzazioni**.

Dopo aver creato il sistema di autorizzazione, collegalo all'instradamento **$connect** della tua API.

**Per collegare un sistema di autorizzazione all'instradamento $connect**

1. Nel pannello di navigazione principale scegli **Instradamenti**.

1. Scegli l'instradamento **$connect**.

1. Nella sezione **Impostazioni della richiesta di instradamento** scegli **Modifica**.

1. Per **Autorizzazione**, scegli il menu a discesa, quindi seleziona il sistema di autorizzazione della richiesta.

1. Scegli **Save changes** (Salva modifiche).

## Passaggio 4: creare un'integrazione bidirezionale fittizia
<a name="websocket-api-step-functions-create-mock-integration"></a>

A questo punto creerai l'integrazione bidirezionale fittizia per l'instradamento **$default**. Un'integrazione fittizia consente di inviare una risposta al client senza utilizzare un backend. Quando crei un'integrazione per l'instradamento **$default**, puoi mostrare ai client come interagire con la tua API.

Configura l'instradamento **$default** per indicare ai client di utilizzare l'instradamento **sendmessage**.

**Per creare un'integrazione fittizia**

1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)

1. Scegli l'instradamento **$default**, quindi scegli la scheda **Richiesta di integrazione**.

1. Per **Modelli di richiesta**, scegli **Modifica**.

1. Per **Espressione di selezione del modello**, inserisci **200**, quindi scegli **Modifica**.

1. Nella scheda **Richiesta di integrazione**, in **Modelli di richiesta**, scegli **Crea modello**.

1. Per **Chiave del modello**, inserisci **200**.

1. Per **Genera modello**, inserisci il seguente modello di mappatura:

   ```
   {"statusCode": 200}
   ```

   Scegli **Crea modello**.

   Il risultato sarà simile al seguente:  
![Configurazione della richiesta di integrazione per l'integrazione fittizia per l'instradamento $default.](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/ws-sfn-mock-integration-request.png)

1. Nel riquadro **Instradamento $default**, scegli **Abilita la comunicazione bidirezionale**.

1. Scegli la scheda **Risposta di integrazione**, quindi scegli **Crea risposta di integrazione**.

1. Per **Chiave della risposta**, inserisci **$default**.

1. Per **Espressione di selezione del modello**, inserisci **200**.

1. Scegli **Crea risposta**.

1. Per **Modelli di risposta**, scegli **Crea modello**.

1. Per **Chiave del modello**, inserisci **200**.

1. Per **Modello di risposta**, inserisci il seguente modello di mappatura:

   ```
   {"Use the sendmessage route to send a message. Connection ID: $context.connectionId"}
   ```

1. Scegli **Crea modello**.

   Il risultato sarà simile al seguente:  
![Configurazione della risposta di integrazione per l'integrazione fittizia per l'instradamento $default.](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/ws-sfn-mock-integration-response.png)

## Passaggio 5: creare un'integrazione non proxy con Step Functions
<a name="websocket-api-step-functions-create-step-function-integration"></a>

A questo punto creerai un instradamento **sendmessage**. I client possono invocare l'instradamento **sendmessage** per trasmettere un messaggio a tutti i client connessi. Il percorso **sendmessage** ha un'integrazione del servizio non proxy con. AWS AWS Step Functions L'integrazione richiama il [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)comando per la macchina a stati Step Functions che il CloudFormation modello ha creato per te.

**Per creare un'integrazione non proxy**

1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)

1. Selezionare **Create Route (Crea route)**.

1. Per **Chiave instradamento**, inserisci **sendmessage**.

1. Per **Tipo di integrazione** scegli **Servizio AWS **.

1. Per **AWS Regione**, inserisci la regione in cui hai distribuito il modello. CloudFormation 

1. Per **Servizio AWS **, scegli **Step Functions**.

1. Per **Metodo HTTP**, scegli **POST**.

1. Per **Nome azione** immetti **StartExecution**.

1. Per **Ruolo di esecuzione**, inserisci il ruolo di esecuzione creato dal CloudFormation modello. Il nome deve essere **WebsocketTutorialApiRole**.

1. Selezionare **Create Route (Crea route)**.

A questo punto creerai un modello di mappatura per inviare i parametri di richiesta alla macchina a stati Step Functions.

**Per creare un modello di mappatura**

1. Scegli l'instradamento **sendmessage**, quindi scegli la scheda **Richiesta di integrazione**.

1. Nella sezione **Modelli di richiesta**, scegli **Modifica**.

1. Per **Espressione di selezione del modello**, inserisci **\\$default**.

1. Scegli **Modifica**.

1. Nella sezione **Modelli di richiesta**, scegli **Crea modello**.

1. Per **Chiave del modello**, inserisci **\\$default**.

1. Per **Genera modello**, inserisci il seguente modello di mappatura:

   ```
   #set($domain = "$context.domainName")
   #set($stage = "$context.stage")
   #set($body = $input.json('$'))
   #set($getMessage = $util.parseJson($body))
   #set($mymessage = $getMessage.message)
   {
   "input": "{\"domain\": \"$domain\", \"stage\": \"$stage\", \"message\": \"$mymessage\"}",
   "stateMachineArn": "arn:aws:states:{{us-east-2}}:{{123456789012}}:stateMachine:WebSocket-Tutorial-StateMachine"
   }
   ```

   Sostituire {{stateMachineArn}} con l'ARN della macchina a stati creata da. CloudFormation

   Questo modello di mappatura esegue queste operazioni:
   + Crea la variabile `$domain` utilizzando la variabile di contesto `domainName`.
   + Crea la variabile `$stage` utilizzando la variabile di contesto `stage`.

     Le variabili `$domain` e `$stage` sono necessarie per creare un URL di callback.
   + Riceve il messaggio JSON `sendmessage` in arrivo ed estrae la proprietà `message`.
   + Crea l'input per la macchina a stati. L'input è il dominio e lo stadio dell' WebSocket API e il messaggio proveniente dalla `sendmessage` route.

1. Scegli **Crea modello**.  
![Configurazione dell'instradamento sendmessage.](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/ws-sfn-integration-request.png)

È possibile creare un'integrazione non proxy sugli instradamenti **$connect** o **$disconnect** per aggiungere o rimuovere direttamente un ID di connessione dalla tabella DynamoDB, senza invocare una funzione Lambda.

## Fase 6: Test dell'API
<a name="websocket-api-step-functions-test-api"></a>

A questo punto distribuirai e testerai l'API per assicurarti che funzioni correttamente. Utilizzerai il `wscat` comando per connetterti all'API e poi utilizzerai un comando slash per inviare un frame ping per verificare la connessione all' WebSocket API.

**Per distribuire l'API**

1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)

1. Nel pannello di navigazione principale scegli **Instradamenti**.

1. Seleziona **Deploy API (Distribuisci API)**.

1. Per **Fase**, scegli **produzione**.

1. (Facoltativo) Inserisci una descrizione in **Descrizione distribuzione**.

1. Seleziona **Deploy (Implementa)**.

Dopo aver distribuito l'API, puoi invocarla. Utilizza l'URL di richiamo per chiamare la tua API.

**Per ottenere l'URL di richiamo dell'API**

1. Scegliere l'API.

1. Scegli **Stages** (Fasi), quindi scegli **production** (produzione).

1. **Annota l'URL della tua API. WebSocket ** L'URL dovrebbe essere del tipo `wss://{{abcdef123}}.execute-api.{{us-east-2}}.amazonaws.com/production`.

Ora che hai l'URL di invoke, puoi testare la connessione alla tua WebSocket API.

**Per testare la connessione all'API**

1. Per connetterti all'API, utilizza il seguente comando. Innanzitutto, testa la connessione invocando il percorso `/ping`.

   ```
   wscat -c wss://{{abcdef123}}.execute-api.{{us-east-2}}.amazonaws.com/production -H "Authorization: Allow" --slash -P
   ```

   ```
   Connected (press CTRL+C to quit)
   ```

1. Immetti i seguenti comandi per eseguire il ping del frame di controllo. Puoi utilizzare un frame di controllo per il keepalive dal lato client.

   ```
   /ping
   ```

   Il risultato sarà simile al seguente:

   ```
   < Received pong (data: "")
   ```

Ora che hai testato la connessione, puoi verificare che la tua API funzioni correttamente. In questo passaggio, apri una nuova finestra di terminale in modo che l' WebSocket API possa inviare un messaggio a tutti i client connessi.

**Per testare l'API**

1. Apri un nuovo terminale ed esegui nuovamente il comando `wscat` con i parametri seguenti.

   ```
   wscat -c wss://{{abcdef123}}.execute-api.{{us-east-2}}.amazonaws.com/production -H "Authorization: Allow"
   ```

   ```
   Connected (press CTRL+C to quit)
   ```

1. Gateway API determina quale instradamento invocare in base all'espressione di selezione della richiesta di instradamento dell'API. L'espressione di selezione dell'instradamento dell'API è `$request.body.action`. Di conseguenza, API Gateway richiama il routing `sendmessage` quando si invia il seguente messaggio:

   ```
   {"action": "sendmessage", "message": "hello, from Step Functions!"}
   ```

   La macchina a stati Step Functions associata all'instradamento invoca una funzione Lambda con il messaggio e l'URL di callback. La funzione Lambda chiama l'API di gestione di Gateway API e invia il messaggio a tutti i client connessi. Tutti i client connessi ricevono il seguente messaggio:

   ```
   < hello, from Step Functions!
   ```

Ora che hai testato la tua WebSocket API, puoi disconnetterti dalla tua API.

**Per disconnetterti dall'API**
+ Per disconnetterti dall'API, premi `CTRL+C`.

  Quando un client si disconnette dall'API, Gateway API invoca l'instradamento **$disconnect** dell'API. L'integrazione Lambda per l'instradamento **$disconnect** dell'API rimuove l'ID di connessione da DynamoDB.

## Fase 7: pulire
<a name="websocket-api-step-functions-cleanup"></a>

Per evitare costi non necessari, eliminare le risorse create nell'ambito di questo tutorial. I passaggi seguenti eliminano lo CloudFormation stack e WebSocket l'API.

**Per eliminare un'API WebSocket**

1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)

1. **Nella **APIs**pagina, seleziona il tuo websocket-api.**

1. Scegliere **Azioni**, scegliere **Elimina**, quindi confermare la scelta.

**Per eliminare uno stack CloudFormation**

1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)

1. Seleziona il tuo stack. CloudFormation 

1. Scegli **Elimina** e conferma la tua scelta.

## Passaggi successivi
<a name="websocket-api-step-functions-next-steps"></a>

Puoi automatizzare la creazione e la pulizia di tutte le AWS risorse coinvolte in questo tutorial. [Per un esempio di CloudFormation modello che automatizza queste azioni per questo tutorial, vedi ws-sfn.zip.](samples/ws-sfn-complete.zip)