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 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:

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.

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.

Sintaxe da solicitação

GET /connect
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%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 para o Horário 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:

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 as https://docs.aws.amazon.com/STS/últimas//APIReference.

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:

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:

Este exemplo mostra como usar prefetch-on=connect.

GET /connect
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%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: ChannelSummary 
        ChannelMessages: List of ChannelMessageSummary  
        ChannelMemberships: List of ChannelMembershipSummary
        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 CreateChannelMembership.

Um AppInstanceAdmin e um ChannelModerator não recebem mensagens em um canal, a menos que você use a API CreateChannelMembership para adicioná-los explicitamente.

Os tópicos a seguir explicam como processar eventos.

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:

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:

x-amz-chime-message-tipo

A tabela a seguir lista os tipos de mensagens x-amz-chime-message-type.

x-amz-chime-event-razão

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.

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:

Para códigos 4XXX, sempre se reconecte, exceto pelas seguintes mensagens:

Quando o aplicativo usa um código de fechamento para se reconectar, o aplicativo deve:

Se você usar a amazon-chime-sdk-js biblioteca, isso será tratado se você implementar a propriedade needsRefresh () e o método refresh (). 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.