Como definir uma política do IAM Recuperação do endpoint Como estabelecer a conexão Usar a pré-busca Processar os eventos

Usando WebSockets para receber mensagens

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:

Tópicos

Como definir uma política do IAM
Recuperação do endpoint
Como estabelecer a conexão
Usar a pré-busca para fornecer detalhes do canal
Processar os eventos

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.

Use a GetMessagingSessionEndpointAPI para recuperar o WebSocket endpoint.
Use a URL retornada pela GetMessagingSessionEndpointAPI 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.

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 obter mais informações sobre como assinar uma solicitação, consulte Assinando AWS solicitações com o Signature versão 4.

nota

Para recuperar o endpoint, você pode invocar a API. GetMessagingSessionEndpoint 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%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:

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/.

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 ChannelMessageSummaryobjetos, ordenada por CreatedTimestamp 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 ChannelMembershipSummaryobjetos. 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%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 CreateChannelMembershipAPI.

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.

An AppInstanceAdmin e a ChannelModerator não recebem mensagens em um canal, a menos que você use a CreateChannelMembershipAPI para adicioná-las explicitamente.

Os tópicos a seguir explicam como processar eventos.

Tópicos

Noções básicas das estruturas de mensagens
Como lidar com desconexões

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:

EventType	Formato da carga
`SESSION_ESTABLISHED`	N/A. Essa mensagem é enviada uma vez após o usuário se conectar 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`	ChannelMessage
`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`	Channel (Canal) O objeto ChannelSummary. ChannelMessages Lista de ChannelMessageSummaryobjetos, ordenada por `CreatedTimestamp` ordem decrescente. Inclui as 20 mensagens mais recentes, mas você pode ajustar esse limite no nível da conta da AWS. ChannelMemberships Lista de objetos ChannelMembershipSummary. Retorna no máximo 30 membros do canal, mas você pode ajustar esse limite no nível da conta da AWS. ReadMarkerCarimbo de data/hora A hora em que o `AppInstanceUser` marcou o canal como lido pela última vez.
`UPDATE_CHANNEL`	Channel
`DELETE_CHANNEL`	Channel
`BATCH_CREATE_CHANNEL_MEMBERSHIP`	BatchChannelMembership
`CREATE_CHANNEL_MEMBERSHIP`	ChannelMembership
`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	Descrição
`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	Descrição
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:

Chame a GetMessagingSessionEndpointAPI novamente para obter um novo URL base.
Atualize as credenciais do IAM se elas tiverem expirado.
Conecte-se por meio do WebSocket.

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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Usando ExpirationSettings

Configuração de anexos