As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Usando WebSockets para receber mensagens no Amazon Chime SDK Você pode usar o [Amazon Chime JS SDK](https://github.com/aws/amazon-chime-sdk-js) para receber mensagens usando WebSockets, ou você pode usar a biblioteca WebSocket cliente de sua escolha. Siga estes tópicos na ordem listada para começar a usar WebSockets: **Topics** + [Como definir uma política do IAM](#define-iam-policy) + [Recuperação do endpoint](#retrieve-endpoint) + [Como estabelecer a conexão](#connect-api) + [Usar a pré-busca para fornecer detalhes do canal](#prefetch) + [Processar os eventos](#process-events) ## Como definir uma política do IAM Para começar, defina uma política do IAM que lhe dê permissão para estabelecer uma WebSocket conexão. O exemplo de política a seguir dá `AppInstanceUser` permissão para estabelecer uma WebSocket conexão. ``` "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": [ "*" ] } ] } ``` ## Recuperação do endpoint As etapas a seguir explicam como recuperar o endpoint usado em uma WebSocket conexão. 1. Use a [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 para recuperar o WebSocket endpoint. 1. Use a URL retornada pela [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 para criar uma WebSocket URL assinada Signature versão 4. Se precisar de ajuda para fazer isso, você pode seguir as instruções em [Como estabelecer a conexão](#connect-api). **nota** WebSocket Os URLs têm o seguinte formato: `{{id}}.{{region}}.ws-messaging.chime.aws` ## Como estabelecer a conexão Depois de recuperar um endpoint, você usa a API de conexão para estabelecer uma WebSocket conexão com o servidor back-end do Amazon Chime SDK e receber mensagens para um. `AppInstanceUser` Você deve usar o AWS Signature Version 4 para assinar solicitações. Para ter mais informações sobre como assinar uma solicitação, consulte [ Signing AWS Requests with Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html). **nota** Para recuperar o endpoint, é possível invocar a 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). Você pode usar a biblioteca WebSocket cliente de sua escolha para se conectar ao endpoint. **Sintaxe da solicitação** ``` 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}} ``` **Parâmetros da solicitação de URI** Todos os parâmetros de consulta de solicitação de URI devem ser codificados em URL. **X-Amz-Algorithm** Identifica a versão da AWS assinatura e o algoritmo que você usou para calcular a assinatura. O SDK do Amazon Chime suporta somente a autenticação AWS Signature Version 4, então o valor disso é `AWS4-HMAC-SHA256`. **X-Amz-Credential** Além do ID da chave de acesso, esse parâmetro também fornece a AWS região e o serviço — o escopo — para os quais a assinatura é válida. O valor deve corresponder ao escopo usado nos cálculos de assinatura. A forma geral para esse valor do parâmetro é: `<{{yourAccessKeyId}}>/<{{date}}>/<{{awsRegion}}>/<{{awsService}} >/aws4_request` Por exemplo: `AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request` **X-Amz-Date** O formato de data e hora deve seguir o padrão ISO 8601 e o formato deve ser `yyyyMMddTHHmmssZ`. Por exemplo, você deve converter **08/01/2020 15:32:41.982-700** em Tempo Universal Coordenado (UTC) e enviá-lo como. `20200801T083241Z` **X-Amz-Signed-Headers** Lista os cabeçalhos usados para calcular a assinatura. Os seguintes cabeçalhos são obrigatórios para os cálculos da assinatura: + O cabeçalho do host HTTP. + Todo cabeçalho x-amz-\* que você pretende adicionar à solicitação. **nota** Para maior segurança, é necessário assinar todos os cabeçalhos de solicitação que pretende incluir na sua solicitação. **X-Amz-Signatures** Fornece a assinatura para autenticar a solicitação. Essa assinatura deve corresponder à assinatura que o SDK do Amazon Chime calcula. Caso contrário, o SDK do Amazon Chime negará a solicitação. Por exemplo, .`733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7` **X-Amz-Security-Token** Parâmetro de credencial opcional se estiver usando credenciais provenientes do Security Token Service. Para obter mais informações sobre o serviço, consulte [https://docs.aws.amazon.com/STS/latest/APIReference/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)o. **SessionId** Indica um ID exclusivo para a WebSocket conexão que está sendo estabelecida. **UserArn** Indica a identidade do `AppInstanceUser` que está tentando estabelecer uma conexão. O valor deve ser o ARN do `AppInstanceUser`. Por exemplo, `arn:aws:chime:{{us%2Deast%2D1}}:{{123456789012}}:app%2Dinstance/{{694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e}}/user/{{johndoe}}`. ## Usar a pré-busca para fornecer detalhes do canal Ao estabelecer uma WebSocket conexão, você pode especificar `prefetch-on=connect` em seus parâmetros de consulta a entrega de `CHANNEL_DETAILS` eventos. O atributo de pré-busca vem com a API do Connect, e o atributo permite que os usuários tenham uma visualização do chat enriquecida sem chamadas extras de API. Os usuários podem: + Veja uma prévia da última mensagem do canal, além da data e hora. + Veja os membros de um canal. + Veja os marcadores não lidos de um canal. Depois que um usuário se conecta com o parâmetro de pré-busca especificado, ele recebe o evento estabelecido pela sessão, que indica que a conexão foi estabelecida. O usuário então recebe até 50 eventos `CHANNEL_DETAILS`. Se o usuário tiver menos de 50 canais, a API do Connect pré-busca todos os canais por meio de eventos `CHANNEL_DETAILS`. Se o usuário tiver mais de 50 canais, a API pré-busca os 50 principais canais que contêm mensagens não lidas e os valores `LastMessageTimestamp` mais recentes. Os eventos `CHANNEL_DETAILS` chegam em ordem aleatória e você recebe eventos para todos os 50 canais. Além disso, a pré-busca retorna o seguinte para `ChannelMessages` e `ChannelMemberships`: + **ChannelMessages**: lista de objetos [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), ordenados por `CreatedTimestamp` em ordem decrescente. Inclui apenas as 20 mensagens mais recentes visíveis para o usuário. Se houver mensagens direcionadas no canal que não estejam visíveis para o usuário atual, menos de 20 mensagens poderão ser retornadas. O valor booleano `ChannelMessagesHasMore` será definido como verdadeiro para indicar que há mais mensagens. Limite flexível, ajustável no nível da AWS conta. + **ChannelMemberships**: lista de objetos [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). Inclui no máximo 30 membros do canal. Limite flexível, ajustável no nível AWS da conta. Este exemplo mostra como usar `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}} ``` Este exemplo mostra a resposta de um canal. Você receberá respostas para todos os 50 canais. ``` { "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 }) } ``` ## Processar os eventos Para que um `AppInstanceUser` possa receber mensagens depois de estabelecer uma conexão, você deve adicioná-los a um canal. Para fazer isso, use a API [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). **nota** Um `AppInstanceUser` sempre recebe mensagens de todos os canais aos quais pertence. As mensagens são interrompidas quando o usuário da `AppInstance` se desconecta. Um `AppInstanceAdmin` e um `ChannelModerator` não recebem mensagens em um canal, a menos que você use a API [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) para adicioná-los explicitamente. Os tópicos a seguir explicam como processar eventos. **Topics** + [Noções básicas das estruturas de mensagens](#message-structures) + [Como lidar com desconexões](#handle-disconnects) ### Noções básicas das estruturas de mensagens Cada WebSocket mensagem que você recebe segue este formato: ``` { "Headers": {"{{key}}": "{{value}}"}, "Payload": "{\"{{key}}\": \"{{value}}\"}" } ``` **Cabeçalhos** As mensagens do SDK do Amazon Chime usam as seguintes chaves de cabeçalho: + `x-amz-chime-event-type` + `x-amz-chime-message-type` + `x-amz-chime-event-reason` A próxima seção lista e descreve os possíveis valores e cargas úteis do cabeçalho. **Carga útil** As mensagens do Websocket retornam strings JSON. A estrutura das cadeias de caracteres JSON depende dos cabeçalhos de `x-amz-event-type`. A tabela a seguir lista os valores `x-amz-chime-event-type` e cargas úteis possíveis:
EventTypeFormato da carga
`SESSION_ESTABLISHED`N/A. Essa mensagem é enviada uma vez depois que o usuário se conecta ao WebSocket. Isso indica que qualquer mensagem ou evento em um canal que chega depois que o usuário recebe a `SESSION_ESTABLISHED` mensagem tem a garantia de ser entregue ao usuário, desde que WebSocket permaneça aberto.
`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/pt_br/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`
**x-amz-chime-message-type** A tabela a seguir lista os tipos de mensagens `x-amz-chime-message-type`. | Tipo de mensagem | Description | | --- | --- | | `STANDARD` | Enviado quando o websocket recebe uma mensagem STANDARD do canal. | | `CONTROL` | Enviado quando WebSocket recebe uma mensagem do canal CONTROL. | | `SYSTEM` | Todas as outras mensagens de websocket enviadas pelo Mensagens do SDK do Amazon Chime. | **x-amz-chime-event-reason** Esse é um cabeçalho opcional compatível com um caso de uso específico. O cabeçalho fornece informações sobre o motivo pelo qual um evento específico foi recebido. | Motivos de evento | Description | | --- | --- | | subchannel\_DELETED | Eventos `DELETE_CHANNEL_MEMBERSHIP` recebidos pelos moderadores do canal elástico. Visto apenas pelos moderadores após o balanceamento de membros excluir um subcanal ao qual eles pertenciam. | ### Como lidar com desconexões Os Websockets podem se desconectar devido a alterações na conectividade da rede ou quando as credenciais expirarem. Depois de abrir um WebSocket, o Amazon Chime SDK envia pings regulares para o cliente de mensagens para garantir que ele ainda esteja conectado. Se a conexão for fechada, o cliente receberá um código de WebSocket fechamento. O cliente pode tentar se reconectar ou não, dependendo do código de fechamento. As tabelas a seguir mostram os códigos de fechamento que o cliente pode usar para se reconectar. Para 1000 a 4000 códigos de encerramento, reconecte-se somente para as seguintes mensagens: | Códigos de fechamento | Pode se reconectar | Motivo | | --- | --- | --- | | 1001 | Sim | Fechamento normal | | 1006 | Sim | Fechamento anormal | | 1011 | Sim | Erro interno do servidor | | 1012 | Sim | Reinício do serviço | | 1013 | Sim | Tente novamente mais tarde | | 1014 | Sim | O servidor estava agindo como gateway ou proxy e recebeu uma resposta inválida do servidor upstream. Isso é semelhante ao Código de status HTTP 502. | Para códigos 4XXX, sempre se reconecte, *exceto* pelas seguintes mensagens: | Códigos de fechamento | Pode se reconectar | Motivo | | --- | --- | --- | | 4002 | Não | Iniciado pelo cliente | | 4003 | Não | Proibido | | 4401 | Não | Não autorizado | Quando o aplicativo usa um código de fechamento para se reconectar, o aplicativo deve: 1. Chame a 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) novamente para ter um novo URL base. 1. Atualize as credenciais do IAM se elas tiverem expirado. 1. Conecte-se por meio do WebSocket. Se você usa a biblioteca amazon-chime-sdk-js, isso será tratado se você implementar a propriedade [needsRefresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) e o método [refresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property). Para ver um exemplo prático, consulte [https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx\# L93-L101](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101).