# Nozioni di base su Chat Amazon IVS Amazon IVS (Interactive Video Service) Chat è una funzionalità gestita di chat in tempo reale per accompagnare gli stream video dal vivo. La chat IVS può essere utilizzata anche senza streaming video. È possibile creare chat room e abilitare le sessioni di chat tra i propri utenti. Amazon IVS Chat consente di concentrarsi sulla creazione di esperienze di chat personalizzate insieme a video dal vivo. Non è necessario gestire l'infrastruttura o sviluppare e configurare componenti dei flussi di lavoro di chat. Amazon IVS Chat è scalabile, sicuro, affidabile e conveniente. Amazon IVS Chat è ideale per facilitare la messaggistica tra i partecipanti di uno stream video dal vivo con un inizio e una fine. Il resto di questo documento illustra le fasi necessarie per creare la prima applicazione di chat utilizzando Amazon IVS Chat. **Esempi:** sono disponibili le seguenti app demo (tre app client di esempio e un'app server di backend per la creazione di token): + [Demo di Amazon IVS Chat Web](https://github.com/aws-samples/amazon-ivs-chat-web-demo) + [Demo di Amazon IVS Chat per Android](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo) + [Demo di Amazon IVS Chat per iOS](https://github.com/aws-samples/amazon-ivs-chat-for-ios-demo) + [Demo di backend di Amazon IVS Chat](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless) **Importante:** le chat room che non hanno nuove connessioni o aggiornamenti per 24 mesi vengono automaticamente eliminate. **Topics** + [Fase 1: Esecuzione della configurazione iniziale](getting-started-chat-create-account.md) + [Passaggio 2: creare una chat room](getting-started-chat-create-room.md) + [Passaggio 3: creare un token di chat](getting-started-chat-auth.md) + [Passaggio 4: inviare e ricevere il primo messaggio](getting-started-chat-send-and-receive.md) + [Passaggio 5: verificare i limiti delle Service Quotas (facoltativo)](getting-started-chat-check-service-quota.md) # Fase 1: Esecuzione della configurazione iniziale Per poter procedere, è necessario: 1. Creare un account AWS 1. Configurare gli utenti root e amministrativi 1. Configura le autorizzazioni di AWS IAM (Identity and Access Management). Utilizzare la policy specificata di seguito. Per i passaggi specifici, consulta [Guida introduttiva allo streaming a bassa latenza di IVS](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/getting-started.html) nella *Guida per l'utente di Amazon IVS*. **Importante**: nella "Fase 3: Configurazione delle autorizzazioni IAM", utilizza questa policy per IVS Chat: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ivschat:CreateChatToken", "ivschat:CreateLoggingConfiguration", "ivschat:CreateRoom", "ivschat:DeleteLoggingConfiguration", "ivschat:DeleteMessage", "ivschat:DeleteRoom", "ivschat:DisconnectUser", "ivschat:GetLoggingConfiguration", "ivschat:GetRoom", "ivschat:ListLoggingConfigurations", "ivschat:ListRooms", "ivschat:ListTagsForResource", "ivschat:SendEvent", "ivschat:TagResource", "ivschat:UntagResource", "ivschat:UpdateLoggingConfiguration", "ivschat:UpdateRoom" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "servicequotas:ListServiceQuotas", "servicequotas:ListServices", "servicequotas:ListAWSDefaultServiceQuotas", "servicequotas:ListRequestedServiceQuotaChangeHistoryByQuota", "servicequotas:ListTagsForResource", "cloudwatch:GetMetricData", "cloudwatch:DescribeAlarms" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogDelivery", "logs:GetLogDelivery", "logs:UpdateLogDelivery", "logs:DeleteLogDelivery", "logs:ListLogDeliveries", "logs:PutResourcePolicy", "logs:DescribeResourcePolicies", "logs:DescribeLogGroups", "s3:PutBucketPolicy", "s3:GetBucketPolicy", "iam:CreateServiceLinkedRole", "firehose:TagDeliveryStream" ], "Resource": "*" } ] } ``` ------ # Passaggio 2: creare una chat room A una chat room Amazon IVS sono associate le informazioni di configurazione (ad esempio, la lunghezza massima del messaggio). Le istruzioni in questa sezione mostrano come utilizzare la console o la CLI AWS per configurare le chat room (inclusa la configurazione opzionale per la revisione e/o la registrazione dei messaggi) e creare chat room. # Istruzioni della console per la creazione di una chat room IVS Questi passaggi sono suddivisi in fasi, a partire dalla configurazione iniziale della chat room fino alla creazione della stessa. Facoltativamente, è possibile configurare una stanza in modo che i messaggi vengano revisionati. Ad esempio, si può aggiornare il contenuto o i metadati dei messaggi, negare i messaggi per impedirne l'invio o lasciare passare il messaggio originale. Per informazioni, consultare [Configurazione per esaminare i messaggi della stanza (facoltativo)](#create-room-console-review-messages). Facoltativamente, puoi anche configurare una stanza in modo che i messaggi vengano registrati. Ad esempio, se hai messaggi inviati a una chat room, puoi registrarli su un bucket Amazon S3, Amazon CloudWatch o Amazon Kinesis Data Firehose. Questa procedura è descritta in [Configurazione dei log dei messaggi (facoltativo)](#create-room-console-log-messages). ## Configurazione iniziale di una stanza 1. Aprire la [console di Amazon IVS Chat](https://console.aws.amazon.com/ivs/chat). Si può accedere alla console Amazon IVS anche dalla [Console di gestione AWS](https://console.aws.amazon.com/). 1. Dalla barra di navigazione, utilizzare il menu a discesa **Seleziona una Regione** per scegliere una regione. La nuova stanza verrà creata in questa regione. 1. Nella casella **Get started** (Nozioni di base), in alto a destra, scegliere **Amazon IVS Chat Room** (Chat room di Amazon IVS). Viene visualizzata la finestra **Create room** (Crea stanza). ![\[Creazione di una chat room.\]](http://docs.aws.amazon.com/it_it/ivs/latest/ChatUserGuide/images/Chat_Create_Room.png) 1. In **Setup** (Configurazione), specificare facoltativamente un **nome stanza**. I nomi delle stanze non sono univoci, ma consentono di distinguere le stanze oltre all'ARN (Amazon Resource Name) della stanza. 1. In **Setup > Room configuration** (Configurazione > Configurazione stanza) accettare la **configurazione predefinita** o selezionare **Custom configuration** (Configurazione personalizzata), quindi configurare **Maximum message length** (Lunghezza massima del messaggio) e/o **Maximum message rate** (Frequenza massima del messaggio). 1. Se si desidera rivedere i messaggi, continuare con la sezione [Configurazione per esaminare i messaggi della stanza (facoltativo)](#create-room-console-review-messages) di seguito. Altrimenti, ignorare la sezione (vale a dire, accettare **Gestore di revisione dei messaggi > Disabilitato**) e andare direttamente a [Creazione di una stanza finale](#create-room-console-final). ## Configurazione per esaminare i messaggi della stanza (facoltativo) 1. In **Gestore di revisione dei messaggi**, selezionare **Gestisci con AWS Lambda**. La sezione **Message Review Handler** (Gestore di revisione dei messaggi) si espande per mostrare opzioni aggiuntive. 1. Configurare **Fallback result** (Risultato fallback) per **consentire** o **negare** il messaggio se il gestore non restituisce una risposta valida, rileva un errore o supera il periodo di timeout. 1. Specificare la **funzione Lambda** esistente o utilizzare **Create Lambda function** (Crea funzione Lambda) per creare una nuova funzione. La funzione Lambda deve trovarsi nella stessa regione AWS e nello stesso account AWS della chat room. È necessario concedere al servizio Amazon Chat SDK l'autorizzazione per richiamare la risorsa lambda. La policy basata sulle risorse verrà creata automaticamente per la funzione lambda selezionata. Per ulteriori informazioni sulle autorizzazioni, consulta la pagina [Resource-Based Policy for Amazon IVS Chat](security-iam.md#security-chat-policy-examples). ## Configurazione dei log dei messaggi (facoltativo) 1. In **Message logging** (Registrazione messaggi), seleziona **Automatically log chat messages** (Registra automaticamente i messaggi di chat). La sezione **Message logging** (Registrazione di messaggi) si espande per mostrare opzioni aggiuntive. Puoi aggiungere una configurazione di registrazione esistente a questa stanza o creare una nuova configurazione di registrazione selezionando **Create logging configuration** (Crea configurazione di registrazione). 1. Se scegli una configurazione di registrazione esistente, viene visualizzato un menu a discesa che mostra tutte le configurazioni di registrazione che hai già creato. Selezionane uno dall'elenco e i tuoi messaggi di chat saranno registrati automaticamente in questa destinazione. 1. Se scegli **Crea configurazione di registrazione**, viene visualizzata una finestra modale che consente di creare e personalizzare una nuova configurazione di registrazione. 1. Facoltativamente, specifica un **nome per la configurazione di registrazione**. I nomi delle configurazioni di registrazione, così come i nomi delle stanze, non sono univoci, ma consentono di distinguere le configurazioni di registrazione diverse dall'ARN di configurazione di registrazione. 1. In **Destinazione**, seleziona **Gruppo di log CloudWatch**, **Flusso di distribuzione Kinesis Firehose** o **Bucket Amazon S3** per scegliere la destinazione per i log. 1. A seconda della destinazione, seleziona l'opzione per creare un nuovo gruppo di log **o utilizzare un gruppo di log CloudWatch** esistente, **Kinesis Firehose Delivery Stream** o un **bucket Amazon S3**. 1. Dopo la revisione, scegli **Create** (Crea) per creare una nuova configurazione di registrazione con un ARN univoco. In questo modo la nuova configurazione di registrazione viene automaticamente allegata alla chat room. ## Creazione di una stanza finale 1. Dopo la revisione, scegli **Create chat room** (Crea chat room) per creare una nuova chat room con un ARN univoco. # Istruzioni della CLI per la creazione di una chat room IVS Questo documento illustra i passaggi necessari per creare una Chat room Amazon IVS utilizzando AWS CLI. ## Creazione di una chat room La creazione di una chat room con la AWS CLI è un'opzione avanzata e richiede prima il download e la configurazione della CLI sul computer. Per maggiori dettagli, consultare la [Guida per l'utente dell'interfaccia a riga di comando di AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). 1. Eseguire il comando `create-room` della chat e inviare un nome facoltativo: ``` aws ivschat create-room --name test-room ``` 1. Viene restituita una nuova chat room: ``` { "arn": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6", "id": "string", "createTime": "2021-06-07T14:26:05-07:00", "maximumMessageLength": 200, "maximumMessageRatePerSecond": 10, "name": "test-room", "tags": {}, "updateTime": "2021-06-07T14:26:05-07:00" } ``` 1. Annotare il campo `arn`. Si avrà bisogno di questo campo per creare un token client e connettersi a una chat room. ## Impostazione di una configurazione di registrazione (facoltativo) Come per la creazione di una chat room, l'impostazione di una configurazione di registrazione con AWS CLI è un'opzione avanzata e richiede prima il download e la configurazione della CLI sul computer. Per maggiori dettagli, consultare la [Guida per l'utente dell'interfaccia a riga di comando di AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). 1. Esegui il comando `create-logging-configuration` della chat e inserisci un nome facoltativo e una configurazione di destinazione che rimandi a un bucket Amazon S3 per nome. Questo bucket Amazon S3 deve già essere presente prima di creare la configurazione di registrazione. (Per i dettagli sulla creazione di un bucket Amazon S3, consulta la [documentazione di Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)). ``` aws ivschat create-logging-configuration \ --destination-configuration s3={bucketName=demo-logging-bucket} \ --name "test-logging-config" ``` 1. Viene restituita una nuova configurazione di registrazione: ``` { "Arn": "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ", "createTime": "2022-09-14T17:48:00.653000+00:00", "destinationConfiguration": { "s3": {"bucketName": "demo-logging-bucket"} }, "id": "ABcdef34ghIJ", "name": "test-logging-config", "state": "ACTIVE", "tags": {}, "updateTime": "2022-09-14T17:48:01.104000+00:00" } ``` 1. Annotare il campo `arn`. Questa operazione è necessaria per allegare la configurazione di registrazione alla chat room. 1. Se stai creando una nuova chat room, esegui il comando `create-room` e passa la configurazione di registrazione `arn`: ``` aws ivschat create-room --name test-room \ --logging-configuration-identifiers \ "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ" ``` 1. Se stai aggiornando una chat room esistente, esegui il comando `update-room` e passa la configurazione di registrazione `arn`: ``` aws ivschat update-room --identifier \ "arn:aws:ivschat:us-west-2:12345689012:room/g1H2I3j4k5L6" \ --logging-configuration-identifiers \ "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ" ``` # Passaggio 3: creare un token di chat Affinché un partecipante alla chat possa connettersi a una stanza e iniziare a inviare e ricevere messaggi, è necessario creare un token di chat. I token di chat vengono utilizzati per autenticare e autorizzare i client delle chat. Questo diagramma illustra il flusso di lavoro per la creazione di un token di chat IVS: ![\[Autenticare e autorizzare i propri client per la chat room appena creata.\]](http://docs.aws.amazon.com/it_it/ivs/latest/ChatUserGuide/images/Chat_Getting_Started_Auth.png) Come mostrato sopra, un'applicazione client richiede un token all'applicazione lato server e l'applicazione lato server chiama CreateChatToken utilizzando un SDK AWS o richieste firmate [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html). Poiché le credenziali AWS vengono utilizzate per chiamare l'API, il token deve essere generato in un'applicazione sicura lato server, non nell'applicazione lato client. Un'applicazione server di backend che mostra come generare token è disponibile all'indirizzo [Demo di backend di Amazon IVS Chat](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless). *Durata della sessione* si riferisce alla durata per cui una sessione stabilita può rimanere attiva prima che venga terminata automaticamente. Ciò significa che la durata della sessione è la durata per cui il client può rimanere connesso alla chat room prima che sia necessario generare un nuovo token e stabilire una nuova connessione. Facoltativamente, è possibile specificare la durata della sessione durante la creazione del token. Ogni token può essere utilizzato una sola volta per stabilire una connessione per un utente finale. Se una connessione viene interrotta, è necessario creare un nuovo token prima che la connessione possa essere ristabilita. Il token stesso è valido fino al timestamp di scadenza del token incluso nella risposta. Quando un utente finale desidera connettersi a una chat room, il client deve chiedere all'applicazione server un token. L'applicazione server crea un token e lo ritrasmette al client. I token devono essere creati per gli utenti finali su richiesta. Per creare un token di autenticazione per la chat, seguire le istruzioni riportate di seguito. Quando si crea un token di chat, utilizza i campi della richiesta per inviare i dati sull'utente finale della chat e sulle funzionalità di messaggistica dell'utente finale. Per i dettagli, consulta [CreateChatToken](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/API_CreateChatToken.html) nella *Documentazione di riferimento dell'API Chat IVS*. ## Istruzioni per SDK AWS La creazione di un token di chat con l'SDK AWS richiede prima il download e la configurazione dell'SDK sull'applicazione. Di seguito sono riportate le istruzioni per l'SDK AWS che utilizza JavaScript. **Importante:** questo codice deve essere eseguito sul lato server e il relativo output passato al client. **Prerequisito**: per utilizzare l'esempio di codice riportato di seguito, è necessario caricare l'SDK AWS JavaScript nell'applicazione. Per informazioni dettagliate, consultare [Guida introduttiva all'SDK AWS per JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html). ``` async function createChatToken(params) { const ivs = new AWS.Ivschat(); const result = await ivs.createChatToken(params).promise(); console.log("New token created", result.token); } /* Create a token with provided inputs. Values for user ID and display name are from your application and refer to the user connected to this chat session. */ const params = { "attributes": { "displayName": "DemoUser", }", "capabilities": ["SEND_MESSAGE"], "roomIdentifier": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6", "userId": 11231234 }; createChatToken(params); ``` ## Istruzioni per la CLI La creazione di un token di chat con la AWS CLI è un'opzione avanzata e richiede prima il download e la configurazione della CLI sul computer. Per maggiori dettagli, consultare la [Guida per l'utente dell'interfaccia a riga di comando di AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). Nota: la generazione di token con l'AWS CLI è utile per scopi di test, ma per l'uso in produzione, si consiglia di generare token sul lato server con l'SDK AWS (vedere le istruzioni sopra). 1. Eseguire il comando `create-chat-token` insieme all'identificatore della stanza e all'ID utente per il client. Includere una delle funzionalità seguenti: `"SEND_MESSAGE"`, `"DELETE_MESSAGE"` ,`"DISCONNECT_USER"`. Facoltativamente, includere la durata della sessione (in minuti) e/o attributi personalizzati (metadati) su questa sessione di chat. Questi campi non sono mostrati di seguito. ``` aws ivschat create-chat-token --room-identifier "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6" --user-id "11231234" --capabilities "SEND_MESSAGE" ``` 1. Viene restituito un token di client: ``` { "token": "abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234.abcd12345EFGHI67890_jklmno123PQRS567890uvwxyz1234abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234abcde", "sessionExpirationTime": "2022-03-16T04:44:09+00:00", "tokenExpirationTime": "2022-03-16T03:45:09+00:00" } ``` 1. Salvare questo token. Si avrà bisogno di questo token per connettersi alla chat room e inviare o ricevere messaggi. Sarà necessario generare un altro token di chat prima della fine della sessione (come indicato da `sessionExpirationTime`). # Passaggio 4: inviare e ricevere il primo messaggio Usare il token di chat per connettersi a una chat room e inviare il primo messaggio. Il codice JavaScript di esempio è fornito di seguito. Sono disponibili anche gli SDK client; consulta [SDK di Chat: guida per Android](chat-sdk-android.md), [SDK di Chat: guida per iOS](chat-sdk-ios.md) e [SDK di Chat: guida per JavaScript](chat-sdk-js.md). **Servizio regionale:** il codice di esempio riportato di seguito si riferisce alla "regione di scelta supportata". Amazon IVS Chat offre endpoint regionali utilizzabili per effettuare le richieste. Per l'Amazon IVS Chat Messaging API (API di Amazon IVS Chat Messaging), la sintassi generale di un endpoint regionale è: + wss://edge.ivschat..amazonaws.com Ad esempio, wss://edge.ivschat.us-west-2.amazonaws.com è l'endpoint della regione Stati Uniti occidentali (Oregon). Per un elenco delle regioni supportate, consultare le informazioni di Amazon IVS Chat nella [pagina di Amazon IVS](https://docs.aws.amazon.com/general/latest/gr/ivs.html) nella *Documentazione di riferimento generale di AWS*. ``` /* 1. To connect to a chat room, you need to create a Secure-WebSocket connection using the client token you created in the previous steps. Use one of the provided endpoints in the Chat Messaging API, depending on your AWS region. */ const chatClientToken = "GENERATED_CHAT_CLIENT_TOKEN_HERE"; const socket = "wss://edge.ivschat.us-west-2.amazonaws.com"; // Replace “us-west-2” with supported region of choice. const connection = new WebSocket(socket, chatClientToken); /* 2. You can send your first message by listening to user input in the UI and sending messages to the WebSocket connection. */ const payload = { "Action": "SEND_MESSAGE", "RequestId": "OPTIONAL_ID_YOU_CAN_SPECIFY_TO_TRACK_THE_REQUEST", "Content": "text message", "Attributes": { "CustomMetadata": "test metadata" } } connection.send(JSON.stringify(payload)); /* 3. To listen to incoming chat messages from this WebSocket connection and display them in your UI, you must add some event listeners. */ connection.onmessage = (event) => { const data = JSON.parse(event.data); displayMessages({ display_name: data.Sender.Attributes.DisplayName, message: data.Content, timestamp: data.SendTime }); } function displayMessages(message) { // Modify this function to display messages in your chat UI however you like. console.log(message); } /* 4. Delete a chat message by sending the DELETE_MESSAGE action to the WebSocket connection. The connected user must have the "DELETE_MESSAGE" permission to perform this action. */ function deleteMessage(messageId) { const deletePayload = { "Action": "DELETE_MESSAGE", "Reason": "Deleted by moderator", "Id": "${messageId}" } connection.send(deletePayload); } ``` Congratulazioni, è tutto pronto\$1 Ora si dispone di un'applicazione di chat semplice in grado di inviare o ricevere messaggi. # Passaggio 5: verificare i limiti delle Service Quotas (facoltativo) Le chat room saranno scalabili insieme allo streaming live di Amazon IVS, per consentire a tutti i visualizzatori di partecipare alle conversazioni in chat. Tuttavia, tutti gli account Amazon IVS hanno dei limiti sul numero di partecipanti alla chat simultanei e sulla velocità di consegna dei messaggi. *Assicurarsi che i propri limiti siano adeguati e richiedere un aumento se necessario, specialmente se si pianifica un evento di streaming di grandi dimensioni*. Per i dettagli, consulta le pagine [Service Quotas (streaming a bassa latenza)](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/service-quotas.html), [Service Quotas (streaming in tempo reale)](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/service-quotas.html) e [Service Quotas (chat)](service-quotas.md).