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à. # Utilizzo WebSockets per ricevere messaggi nella messaggistica SDK di Amazon Chime Puoi utilizzare l'[SDK Amazon Chime JS](https://github.com/aws/amazon-chime-sdk-js) per ricevere messaggi oppure puoi utilizzare la libreria WebSocket client di tua scelta. WebSockets Segui questi argomenti nell'ordine elencato per iniziare a utilizzare: WebSockets **Topics** + [Definizione di una policy IAM](#define-iam-policy) + [Recupero dell'endpoint](#retrieve-endpoint) + [Stabilire la connessione](#connect-api) + [Utilizzo di prefetch per fornire i dettagli del canale](#prefetch) + [Elaborazione degli eventi](#process-events) ## Definizione di una policy IAM Per iniziare, definisci una policy IAM che ti dia il permesso di stabilire una WebSocket connessione. La seguente politica di esempio fornisce `AppInstanceUser` il permesso di stabilire una WebSocket connessione. ``` "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action: [ "chime:Connect" ], "Resource": [ "arn:aws:chime:{{region}}:{{{aws_account_id}}}:app-instance/{{{app_instance_id}}}/user/{{{app_instance_user_id}}}" ] }, { "Effect": "Allow", "Action: [ "chime:GetMessagingSessionEndpoint" ], "Resource": [ "*" ] } ] } ``` ## Recupero dell'endpoint I passaggi seguenti spiegano come recuperare l'endpoint utilizzato in una connessione. WebSocket 1. Utilizza l'[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API per recuperare l'endpoint. WebSocket 1. Utilizza l'URL restituito dall'[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API per creare un URL firmato Signature Version 4. WebSocket Se hai bisogno di aiuto per farlo, puoi seguire le istruzioni in. [Stabilire la connessione](#connect-api) **Nota** WebSocket Gli URL hanno il seguente formato: `{{id}}.{{region}}.ws-messaging.chime.aws` ## Stabilire la connessione Dopo aver recuperato un endpoint, utilizzi l'API connect per stabilire una WebSocket connessione al server back-end Amazon Chime SDK e ricevere messaggi per un. `AppInstanceUser` È necessario utilizzare AWS Signature Version 4 per firmare le richieste. Per ulteriori informazioni sulla firma di una richiesta, consulta [Firmare AWS le richieste con la versione 4 della firma](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html). **Nota** Per recuperare l'endpoint, puoi richiamare l'API. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) Puoi utilizzare la libreria WebSocket client di tua scelta per connetterti all'endpoint. **Sintassi della richiesta** ``` GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential={{AKIARALLEXAMPLE%2F20201214}}%2F{{region}}%2Fchime%2Faws4_request &X-Amz-Date={{20201214T171359Z}} &X-Amz-Expires={{10}} &X-Amz-SignedHeaders=host &sessionId={{{sessionId}}} &userArn={{{appInstanceUserArn}}} &X-Amz-Signature={{db75397d79583EXAMPLE}} ``` **Parametri di richiesta URI** Tutti i parametri di query di richiesta URI devono essere codificati tramite URL. **X-Amz-Algorithm** Identifica la versione di AWS Signature e l'algoritmo utilizzato per calcolare la firma. L'SDK Amazon Chime supporta solo l'autenticazione AWS Signature Version 4, quindi il suo valore è. `AWS4-HMAC-SHA256` **X-Amz-Credential** Oltre all'ID della chiave di accesso, questo parametro fornisce anche la AWS regione e il servizio, ovvero l'ambito, per i quali la firma è valida. Questo valore deve corrispondere all'ambito utilizzato nei calcoli delle firme. La forma generale per questo valore di parametro è: `<{{yourAccessKeyId}}>/<{{date}}>/<{{awsRegion}}>/<{{awsService}} >/aws4_request` Esempio: `AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request` **X-Amz-Date** Il formato di data e ora deve essere conforme allo standard ISO 8601 ed è necessario formattarlo come`yyyyMMddTHHmmssZ`. Ad esempio, è necessario convertire **08/01/2020 15:32:41.982-700** in Coordinated Universal Time (UTC) e inviarlo come. `20200801T083241Z` **X-Amz-Signed-Headers** Elenca le intestazioni che hai utilizzato per calcolare la firma. Per i calcoli delle firme sono necessarie le seguenti intestazioni: + L'intestazione dell'host HTTP. + Qualsiasi intestazione x-amz-\* che intendi aggiungere alla richiesta. **Nota** Per una maggiore sicurezza, firma tutte le intestazioni di richiesta che intendi includere nella richiesta. **X-Amz-Signatures** Fornisce la firma per autenticare la richiesta. Questa firma deve corrispondere alla firma calcolata da Amazon Chime SDK. In caso contrario, Amazon Chime SDK nega la richiesta. Ad esempio, `733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7`. **X-Amz-Security-Token** Parametro di credenziale opzionale se si utilizzano credenziali provenienti dal servizio Security Token. Per ulteriori informazioni sul servizio, vedere. [https://docs.aws.amazon.com/STS/latest/APIReference/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) **SessionId** Indica un ID univoco per la WebSocket connessione che si sta stabilendo. **UserArn** Indica l'identità del `AppInstanceUser` tentativo di stabilire una connessione. Il valore deve essere l'ARN di. `AppInstanceUser` Ad esempio, `arn:aws:chime:{{us%2Deast%2D1}}:{{123456789012}}:app%2Dinstance/{{694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e}}/user/{{johndoe}}` ## Utilizzo di prefetch per fornire i dettagli del canale Quando si stabilisce una WebSocket connessione, è possibile specificare `prefetch-on=connect` nei parametri di interrogazione per fornire `CHANNEL_DETAILS` eventi. La funzionalità di prefetch viene fornita con l'API connect e consente agli utenti di visualizzare una visualizzazione della chat arricchita senza chiamate API aggiuntive. Gli utenti possono: + Visualizza un'anteprima dell'ultimo messaggio del canale, più il relativo timestamp. + Visualizza i membri di un canale. + Visualizza i marker non letti di un canale. Dopo che un utente si connette con il parametro prefetch specificato, riceve l'evento di sessione stabilita, che indica che la connessione è stata stabilita. L'utente riceve quindi fino a 50 `CHANNEL_DETAILS` eventi. Se l'utente ha meno di 50 canali, l'API connect precarica tutti i canali tramite `CHANNEL_DETAILS` eventi. Se l'utente ha più di 50 canali, l'API prerecupera i primi 50 canali che contengono messaggi non letti e i valori più recenti. `LastMessageTimestamp` Gli `CHANNEL_DETAILS` eventi arrivano in ordine casuale e tu ricevi eventi per tutti i 50 canali. Inoltre, prefetch restituisce quanto segue per `ChannelMessages` e: `ChannelMemberships` + **ChannelMessages**— Elenco di [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html)oggetti, ordinati per `CreatedTimestamp` ordine decrescente. Include solo gli ultimi 20 messaggi visibili all'utente. Se nel canale sono presenti messaggi mirati che non sono visibili all'utente corrente, potrebbero essere restituiti meno di 20 messaggi. Il valore `ChannelMessagesHasMore` booleano verrà impostato su true per indicare che ci sono più messaggi. Limite flessibile, regolabile a livello di AWS account. + **ChannelMemberships**— Elenco degli [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html)oggetti. Include un massimo di 30 membri del canale. Limite flessibile, regolabile a livello di AWS account. Questo esempio mostra come usare`prefetch-on=connect`. ``` GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential={{AKIARALLEXAMPLE}}%2F{{20201214}}%2F{{region}}%2Fchime%2Faws4_request &X-Amz-Date={{20201214T171359Z}} &X-Amz-Expires={{10}} &X-Amz-SignedHeaders=host &sessionId={{sessionId}} &prefetch-on=connect &userArn={{appInstanceUserArn}} &X-Amz-Signature={{db75397d79583EXAMPLE}} ``` Questo esempio mostra la risposta per un canale. Riceverai risposte per tutti i 50 canali. ``` { "Headers": { "x-amz-chime-event-type": "CHANNEL_DETAILS", "x-amz-chime-message-type": "SYSTEM" }, "Payload": JSON.stringify"({ Channel: [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html) ChannelMessages: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) ChannelMemberships: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ) ReadMarkerTimestamp: Timestamp ChannelMessagesHasMore: Boolean }) } ``` ## Elaborazione degli eventi `AppInstanceUser`Affinché un utente riceva messaggi dopo aver stabilito una connessione, è necessario aggiungerli a un canale. Per farlo, usa l'[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)API. **Nota** An riceve `AppInstanceUser` sempre messaggi per tutti i canali a cui appartiene. La messaggistica si interrompe quando l'`AppInstance`utente si disconnette. An `AppInstanceAdmin` e a `ChannelModerator` non ricevono messaggi su un canale a meno che non si utilizzi l'[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)API per aggiungerli esplicitamente. I seguenti argomenti spiegano come elaborare gli eventi. **Topics** + [Comprendere le strutture dei messaggi](#message-structures) + [Gestione delle disconnessioni](#handle-disconnects) ### Comprendere le strutture dei messaggi Ogni WebSocket messaggio che ricevi è conforme a questo formato: ``` { "Headers": {"{{key}}": "{{value}}"}, "Payload": "{\"{{key}}\": \"{{value}}\"}" } ``` **Headers** La messaggistica di Amazon Chime SDK utilizza le seguenti chiavi di intestazione: + `x-amz-chime-event-type` + `x-amz-chime-message-type` + `x-amz-chime-event-reason` La sezione successiva elenca e descrive i valori e i payload possibili dell'intestazione. **Carico utile** I messaggi Websocket restituiscono stringhe JSON. La struttura delle stringhe JSON dipende dalle intestazioni. `x-amz-event-type` La tabella seguente elenca i `x-amz-chime-event-type` valori e i payload possibili:
EventTypeFormato del payload
`SESSION_ESTABLISHED`N/A. Questo messaggio viene inviato una volta dopo che l'utente si è connesso a WebSocket. Indica che è garantito che qualsiasi messaggio o evento su un canale che arriva dopo che l'utente ha ricevuto il `SESSION_ESTABLISHED` messaggio verrà recapitato all'utente fintanto che il messaggio WebSocket rimane aperto.
`CREATE_CHANNEL_MESSAGE` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html)
`REDACT_CHANNEL_MESSAGE`
`UPDATE_CHANNEL_MESSAGE`
`DELETE_CHANNEL_MESSAGE`
`PENDING_CREATE_CHANNEL_MESSAGE`
`PENDING_UPDATE_CHANNEL_MESSAGE`
`FAILED_CREATE_CHANNEL_MESSAGE`
`FAILED_UPDATE_CHANNEL_MESSAGE`
`DENIED_CREATE_CHANNEL_MESSAGE`
`DENIED_UPDATE_CHANNEL_MESSAGE`
`CHANNEL_DETAILS`[See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/chime-sdk/latest/dg/websockets.html)
`UPDATE_CHANNEL` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html)
`DELETE_CHANNEL`
`BATCH_CREATE_CHANNEL_MEMBERSHIP` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html)
`CREATE_CHANNEL_MEMBERSHIP`[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html)
`DELETE_CHANNEL_MEMBERSHIP`
`UPDATE_CHANNEL_MEMBERSHIP`
**tipo di messaggio x-amz-chime-** La tabella seguente elenca i tipi di messaggio. `x-amz-chime-message-type` | Tipo di messaggio | Description | | --- | --- | | `STANDARD` | Inviato quando il websocket riceve un messaggio sul canale STANDARD. | | `CONTROL` | Inviato quando WebSocket riceve un messaggio dal canale CONTROL. | | `SYSTEM` | Tutti gli altri messaggi websocket inviati da Amazon Chime SDK Messaging. | **x-amz-chime-event-reason** Questa è un'intestazione opzionale supportata per un caso d'uso specifico. L'intestazione fornisce informazioni sul motivo per cui è stato ricevuto un evento specifico. | Motivo dell'evento | Description | | --- | --- | | SubChannel\_deleted | `DELETE_CHANNEL_MEMBERSHIP`eventi ricevuti dai moderatori del canale elastico. Visualizzato dai moderatori solo dopo il bilanciamento degli abbonamenti, elimina un sottocanale a cui appartenevano. | ### Gestione delle disconnessioni I Websocket possono disconnettersi a causa di cambiamenti nella connettività di rete o alla scadenza delle credenziali. Dopo aver aperto un WebSocket, l'SDK Amazon Chime invia ping regolari al client di messaggistica per assicurarsi che sia ancora connesso. Se la connessione si chiude, il client riceve un codice di chiusura. WebSocket Il client può provare a riconnettersi o meno, a seconda del codice di chiusura. Le tabelle seguenti mostrano i codici di chiusura che il client può utilizzare per riconnettersi. Per 1000 o 4000 codici di chiusura, riconnettiti solo per i seguenti messaggi: | Codici di chiusura | Può riconnettersi | Motivo | | --- | --- | --- | | 1001 | Sì | Chiusura normale | | 1006 | Sì | Chiusura anomala | | 1011 | Sì | Errore interno del server | | 1012 | Sì | Riavvio del servizio | | 1013 | Sì | Riprova più tardi | | 1014 | Sì | Il server fungeva da gateway o proxy e ha ricevuto una risposta non valida dal server upstream. È simile al codice di stato HTTP 502. | Per i codici 4XXX, riconnettiti sempre *ad eccezione* dei seguenti messaggi: | Codici di chiusura | Può riconnettersi | Motivo | | --- | --- | --- | | 4002 | No | Client avviato | | 4003 | No | Accesso negato | | 4401 | No | Not authorized (Non autorizzato) | Quando l'applicazione utilizza un codice di chiusura per riconnettersi, l'applicazione deve: 1. Richiama nuovamente l'[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html)API per ottenere un nuovo URL di base. 1. Aggiorna le credenziali IAM se sono scadute. 1. Connect tramite WebSocket. [Se utilizzi la libreria amazon-chime-sdk-js, questa operazione viene gestita automaticamente se implementi la proprietà [needsRefresh () e il metodo refresh](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) ().](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property) Per un esempio L93-L101 funzionante [https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx,](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101) consulta \#.