Compartilhar via

Biblioteca de clientes do Chat de Comunicação do Azure para Java – versão 1.3.13

  • Artigo

O Chat de Comunicação do Azure contém as APIs usadas em aplicativos de chat para Serviços de Comunicação do Azure.

Código-fonte | Pacote (Maven) | Documentação | de referência da APIDocumentação do produto

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version>1.3.13</version>
</dependency>

Principais conceitos

Uma conversa de chat é representada por um thread de chat. Todo usuário na conversa de chat é chamado de participante. Os participantes podem conversar entre si em particular em um chat 1:1 ou se amontoar em um chat em grupo 1:N.

Depois de inicializar uma ChatClient classe e ChatThreadClient , você poderá fazer as seguintes operações de chat:

Criar, obter, listar, atualizar e excluir threads de chat

Enviar, obter, listar, atualizar e excluir mensagens de chat

Obter, adicionar e remover participantes

Enviar e obter recibos de leitura

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Definir o ponto de extremidade do Recurso de Comunicação do Azure depois que ele for criado

ponto de extremidade = "https:// Azure-Communication-Resource-Name.communications.azure.com"

Solicitar um token de acesso do usuário

Os tokens de acesso do usuário permitem que você crie aplicativos cliente que se autenticam diretamente nos Serviços de Comunicação do Azure. Gere esses tokens em seu servidor, passe-os de volta para um dispositivo cliente e, em seguida, use-os para inicializar os SDKs dos Serviços de Comunicação.

Saiba como gerar tokens de acesso do usuário de Tokens de Acesso do Usuário

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns, incluindo:

Criar o cliente de chat

String endpoint = "https://<RESOURCE_NAME>.communcationservices.azure.com";

// Your user access token retrieved from your trusted service
String token = "SECRET";
CommunicationTokenCredential credential = new CommunicationTokenCredential(token);

// Initialize the chat client
final ChatClientBuilder builder = new ChatClientBuilder();
builder.endpoint(endpoint)
    .credential(credential);
ChatClient chatClient = builder.buildClient();

Operações de thread de chat

Crie uma conversa de chat

Para criar um cliente de chat, você usará o ponto de extremidade do Serviço de Comunicações e o token de acesso que foi gerado como parte das etapas de pré-requisito. Os tokens de acesso do usuário permitem que você crie aplicativos cliente que se autenticam diretamente nos Serviços de Comunicação do Azure. Depois de gerar esses tokens no servidor, transmita-os novamente para um dispositivo cliente. Você precisa usar a classe CommunicationTokenCredential do SDK Comum para passar o token para seu cliente de chat.

Use o método createChatThread para criar uma conversa de chat. createChatThreadOptions é usado para descrever a solicitação de thread, um exemplo é mostrado no snippet de código abaixo.

  • Use topic para fornecer um tópico de thread;
  • Use participants para listar os participantes do thread a serem adicionados ao thread;

CreateChatThreadResult é a resposta retornada pela criação de um thread de chat. Ele contém um método getChatThread() que retorna o objeto ChatThread que pode ser usado para obter o cliente de thread do qual você pode obter o ChatThreadClient para executar operações no thread criado: adicionar participantes, enviar mensagem etc. O objeto ChatThread também contém o método getId() que recupera a ID exclusiva do thread.

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

ChatParticipant firstParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user2)
    .setDisplayName("Participant Display Name 2");

participants.add(firstParticipant);
participants.add(secondParticipant);

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .setParticipants(participants);
CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);

String chatThreadId = result.getChatThread().getId();

Obter propriedades de um thread de chat

O getChatThreadProperties método recupera as propriedades de um thread do serviço.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient("Id");
ChatThreadProperties chatThreadProperties = chatThreadClient.getProperties();

Excluir um thread

Usar deleteChatThread o método para excluir um thread chatThreadId de chat é a ID exclusiva do thread de chat.

String chatThreadId = "Id";
chatClient.deleteChatThread(chatThreadId);

Obter um cliente de conversa de chat

O método getChatThreadClient retorna um cliente de conversa para uma conversa que já existe. Ele pode ser usado para executar operações no thread criado: adicionar participantes, enviar mensagens etc. chatThreadId é a ID exclusiva do thread de chat existente.

String chatThreadId = "Id";
ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Atualizar um tópico de thread de chat

Usar updateTopic o método para atualizar o tópico topic de um thread é usado para manter o novo tópico do thread.

chatThreadClient.updateTopic("New Topic");

Operações de mensagem de chat

Enviar uma mensagem de chat

Use o sendMessage método para enviar uma mensagem de chat para o thread de chat com o qual o chatThreadClient foi criado. sendChatMessageOptions é usado para descrever a solicitação de mensagem de chat, um exemplo é mostrado no snippet de código abaixo.

  • Use content para fornecer o conteúdo da mensagem de chat;
  • Use priority para especificar o nível de prioridade da mensagem de chat, como 'Normal' ou 'High';
  • Use senderDisplayName para especificar o nome de exibição do remetente;

Uma SendChatMessageResult resposta retornada do envio de uma mensagem de chat contém uma ID, que é a ID exclusiva da mensagem.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Message content")
    .setSenderDisplayName("Sender Display Name");

SendChatMessageResult sendResult = chatThreadClient.sendMessage(sendChatMessageOptions);

Obter uma mensagem de chat

O getMessage método recupera uma mensagem de chat do serviço. chatMessageId é a ID exclusiva da mensagem de chat.

String chatMessageId = "Id";
ChatMessage chatMessage = chatThreadClient.getMessage(chatMessageId);

Obter mensagens de chat

Você pode recuperar mensagens de chat usando o listMessages método no cliente de thread de chat em intervalos especificados (sondagem).

PagedIterable<ChatMessage> chatMessagesResponse = chatThreadClient.listMessages();
chatMessagesResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(message ->
        System.out.printf("Message id is %s.", message.getId()));
});

listMessages retorna a última versão da mensagem, incluindo as edições ou as exclusões que ocorreram na mensagem usando .editMessage() e .deleteMessage().

Para mensagens excluídas, chatMessage.getDeletedOn() retorna um valor datetime que indica quando a mensagem foi excluída.

Para as mensagens editadas, chatMessage.getEditedOn() retorna um datetime indicando quando a mensagem foi editada.

A hora original da criação da mensagem pode ser acessada usando chatMessage.getCreatedOn() e pode ser usada para ordenar as mensagens.

listMessages retorna diferentes tipos de mensagens que podem ser identificadas por chatMessage.getType(). Esses tipos são:

  • text: mensagem de chat regular enviada por um participante do thread.

  • html: mensagem de chat em HTML enviada por um participante da conversa.

  • topicUpdated: mensagem do sistema que indica que o tópico foi atualizado.

  • participantAdded: mensagem do sistema que indica que um ou mais participantes foram adicionados ao thread do chat.

  • participantRemoved: mensagem do sistema que indica que um participante foi removido do thread de chat.

Para obter mais detalhes, confira Tipos de mensagem.

Atualizar uma mensagem de chat

Use updateMessage para atualizar uma mensagem de chat identificada por chatThreadId e messageId. chatMessageId é a ID exclusiva da mensagem de chat. updateChatMessageOptions é usado para descrever a solicitação de uma atualização de mensagem de chat, um exemplo é mostrado no snippet de código abaixo.

  • Use content para fornecer um novo conteúdo de mensagem de chat;
String chatMessageId = "Id";
UpdateChatMessageOptions updateChatMessageOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");

chatThreadClient.updateMessage(chatMessageId, updateChatMessageOptions);

Excluir uma mensagem de chat

Use updateMessage para atualizar uma mensagem de chat identificada por chatMessageId. chatMessageId é a ID exclusiva da mensagem de chat.

String chatMessageId = "Id";
chatThreadClient.deleteMessage(chatMessageId);

Operações de participantes da conversa de chat

Listar participantes do chat

Use listParticipants para recuperar uma coleção paginada que contém os participantes da conversa de chat.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(chatParticipant ->
        System.out.printf("Participant id is %s.", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId()));
});

Adicionar participantes

Use addParticipants o método para adicionar participantes à conversa de chat. participants lista de participantes a serem adicionados ao thread;

  • communicationIdentifier, obrigatório, é o CommunicationIdentifier que você criou usando o CommunicationIdentityClient. Mais informações em: Criar um usuário.
  • display_name, opcional, é o nome de exibição do membro da conversa.
  • share_history_time, opcional, é a hora a partir da qual o histórico de chats é compartilhado com o membro. Para compartilhar o histórico desde o início da conversa de chat, defina essa propriedade como qualquer data igual ou inferior à hora de criação da conversa. Para não compartilhar nenhum histórico anterior ao momento em que o membro foi adicionado, defina-a como a data atual. Para compartilhar o histórico parcial, defina-o como a data necessária.
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

ChatParticipant firstParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user1)
    .setDisplayName("Display Name 1");

ChatParticipant secondParticipant = new ChatParticipant()
    .setCommunicationIdentifier(user2)
    .setDisplayName("Display Name 2");

participants.add(firstParticipant);
participants.add(secondParticipant);

chatThreadClient.addParticipants(participants);

Remover um participante

Use removeParticipant o método para remover um participante da conversa de chat. identifier é o CommunicationIdentifier que você criou.

chatThreadClient.removeParticipant(user);

Operações de confirmação de leitura

Enviar confirmação de leitura

Use sendReadReceipt o método para postar um evento de confirmação de leitura em uma conversa de chat, em nome de um usuário. chatMessageId é a ID exclusiva da mensagem de chat lida.

String chatMessageId = "Id";
chatThreadClient.sendReadReceipt(chatMessageId);

Obter confirmações de leitura

getReadReceipts O método recupera recibos de leitura para uma conversa de chat.

PagedIterable<ChatMessageReadReceipt> readReceiptsResponse = chatThreadClient.listReadReceipts();
readReceiptsResponse.iterableByPage().forEach(resp -> {
    System.out.printf("Response headers are %s. Url %s  and status code %d %n", resp.getHeaders(),
        resp.getRequest().getUrl(), resp.getStatusCode());
    resp.getElements().forEach(readReceipt ->
        System.out.printf("Read message id is %s.", readReceipt.getChatMessageId()));
});

Operações de notificação de digitação

Enviar uma notificação de digitação

Use sendTypingNotification o método para postar um evento de notificação de digitação em uma conversa de chat, em nome de um usuário. typingNotificationOptions é usado para descrever a solicitação de notificação de digitação.

  • Use senderDisplayName para definir o nome de exibição do remetente de notificação;
TypingNotificationOptions options = new TypingNotificationOptions();
options.setSenderDisplayName("Sender Display Name");
chatThreadClient.sendTypingNotificationWithResponse(options, Context.NONE);

Solução de problemas

Em andamento.

Próximas etapas

Confira outras bibliotecas de clientes para o serviço de comunicação do Azure