Biblioteca cliente de Azure Communication Chat para Java: versión 1.3.13

  • Artículo

Azure Communication Chat contiene las API que se usan en las aplicaciones de chat para Azure Communication Services.

Código | fuentePaquete (Maven) | Documentación | de referencia de APIDocumentación del producto

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de 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>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

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

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

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

Conceptos clave

Una conversación de chat se representa mediante un subproceso de chat. A cada usuario de la conversación de chat se le llama participante. Los participantes pueden chatear entre sí de forma privada en un chat de 1:1 o en un chat de grupo de 1:N.

Una vez que haya inicializado una ChatClient clase y ChatThreadClient , puede realizar las siguientes operaciones de chat:

Crear, obtener, enumerar, actualizar y eliminar subprocesos de chat

Enviar, obtener, enumerar, actualizar y eliminar mensajes de chat

Obtener, agregar y quitar participantes

Enviar y obtener recibos de lectura

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Establecimiento del punto de conexión de recursos de comunicación de Azure después de crearlo

endpoint = "https:// Azure-Communication-Resource-Name.communications.azure.com"

Solicitar un token de acceso de usuario

Los tokens de acceso de usuario permiten compilar aplicaciones cliente que se autentiquen directamente en Azure Communication Services. Estos tokens se generan en el servidor, los pasa a un dispositivo cliente y, a continuación, los usa para inicializar los SDK de Communication Services.

Obtenga información sobre cómo generar tokens de acceso de usuario a partir de tokens de acceso de usuario

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes, entre las que se incluyen:

Creación del 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();

Operaciones de subprocesos de chat

Crear un hilo de chat

Para crear un cliente de chat, usará el punto de conexión de Communications Service y el token de acceso que se generó como parte de los pasos de requisitos previos. Los tokens de acceso de usuario permiten compilar aplicaciones cliente que se autentiquen directamente en Azure Communication Services. Después de generar estos tokens en el servidor, vuelva a pasarlos a un dispositivo cliente. Debe usar la clase CommunicationTokenCredential del SDK común para pasar el token al cliente de chat.

Use el método createChatThread para crear un subproceso de chat. createChatThreadOptions se usa para describir la solicitud de subproceso; se muestra un ejemplo en el fragmento de código siguiente.

  • Use topic para dar un tema de subproceso;
  • Use participants para enumerar los participantes del subproceso que se van a agregar al subproceso;

CreateChatThreadResult es la respuesta devuelta por la creación de una conversación de chat. Contiene un método getChatThread() que devuelve el objeto ChatThread que se puede utilizar para obtener el cliente de la conversación de la que se puede obtener ChatThreadClient para realizar operaciones en la conversación creada: agregar participantes, enviar mensaje, etc. El objeto ChatThread también contiene el método getId() que recupera el identificador único de la conversación.

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();

Obtener propiedades de un subproceso de chat

El getChatThreadProperties método recupera las propiedades de un subproceso del servicio.

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

Eliminar un subproceso

Usar deleteChatThread método para eliminar un subproceso chatThreadId de chat es el identificador único del subproceso de chat.

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

Obtención de un cliente de subproceso de chat

El método getChatThreadClient devuelve un cliente de subproceso para un subproceso que ya existe. Se puede usar para realizar operaciones en la conversación creada: agregar participantes, enviar un mensaje, etc. chatThreadId es el identificador único de la conversación del chat existente.

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

Actualización de un tema de subproceso de chat

Use updateTopic el método para actualizar el tema topic de un subproceso para contener el nuevo tema del subproceso.

chatThreadClient.updateTopic("New Topic");

Operaciones de mensajes de chat

Enviar un mensaje de chat

Use el sendMessage método para enviar un mensaje de chat al subproceso de chat con el chatThreadClient que se creó . sendChatMessageOptions se usa para describir la solicitud de mensaje de chat, se muestra un ejemplo en el fragmento de código siguiente.

  • Utilice content para proporcionar el contenido del mensaje de chat.
  • Use priority para especificar el nivel de prioridad del mensaje de chat, como "Normal" o "Alto";
  • Utilice senderDisplayName para especificar el nombre para mostrar del remitente.

Una SendChatMessageResult respuesta devuelta al enviar un mensaje de chat, contiene un identificador, que es el identificador único del mensaje.

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

SendChatMessageResult sendResult = chatThreadClient.sendMessage(sendChatMessageOptions);

Obtener un mensaje de chat

El getMessage método recupera un mensaje de chat del servicio. chatMessageId es el identificador único del mensaje de chat.

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

Obtener mensajes de chat

Puede recuperar mensajes de chat mediante el listMessages método en el cliente de subprocesos de chat a intervalos especificados (sondeo).

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 devuelve la versión más reciente del mensaje, incluidas las modificaciones o eliminaciones que se han producido en este mediante .editMessage() y .deleteMessage().

En el caso de los mensajes eliminados, chatMessage.getDeletedOn() devuelve un valor de fecha y hora que indica cuándo se eliminó el mensaje.

En el caso de los mensajes editados, chatMessage.getEditedOn() devuelve un valor de fecha y hora que indica cuándo se editó el mensaje.

Es posible acceder a la hora original de creación del mensaje mediante chatMessage.getCreatedOn() y se puede usar para ordenar los mensajes.

listMessages devuelve distintos tipos de mensajes que se pueden identificar mediante chatMessage.getType(). Estos tipos son:

  • text: mensaje de chat normal enviado por un participante de la conversación.

  • html: mensaje de chat en formato HTML enviado por un participante de la conversación.

  • topicUpdated: mensaje del sistema que indica que el tema se ha actualizado.

  • participantAdded: mensaje del sistema que indica que se han agregado uno o varios miembros a la conversación del chat.

  • participantRemoved: mensaje del sistema que indica que se ha eliminado un miembro de la conversación del chat.

Para obtener más información, consulte Tipos de mensajes.

Actualizar un mensaje de chat

Use updateMessage para actualizar un mensaje de chat identificado por chatThreadId y messageId. chatMessageId es el identificador único del mensaje de chat. updateChatMessageOptions se usa para describir la solicitud de una actualización de mensajes de chat; se muestra un ejemplo en el fragmento de código siguiente.

  • Use content para proporcionar un nuevo contenido de mensaje de chat;
String chatMessageId = "Id";
UpdateChatMessageOptions updateChatMessageOptions = new UpdateChatMessageOptions()
    .setContent("Updated message content");

chatThreadClient.updateMessage(chatMessageId, updateChatMessageOptions);

Eliminar un mensaje de chat

Use updateMessage para actualizar un mensaje de chat identificado por chatMessageId. chatMessageId es el identificador único del mensaje de chat.

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

Operaciones de participantes de subprocesos de chat

Mostrar participantes del chat

Use listParticipants para recuperar una colección paginada que contiene los participantes del subproceso 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()));
});

Agregar participantes

Use addParticipants el método para agregar participantes al subproceso de chat. participants lista de participantes que se van a agregar al subproceso;

  • communicationIdentifier, obligatorio, es communicationIdentifier que ha creado mediante CommunicationIdentityClient. Más información en: Crear un usuario.
  • El elemento opcional display_name es el nombre para mostrar del miembro de subproceso.
  • El elemento opcional share_history_time es la hora a partir de la cual el historial de chat se compartió con el miembro. Para compartir el historial desde el inicio del subproceso de chat, establezca esta propiedad en cualquier fecha igual o anterior a la hora de creación del subproceso. Para no compartir ningún historial anterior a la hora en que se agregó el miembro, establézcala en la fecha actual. Para compartir el historial parcialmente, establezca la opción en la fecha necesaria.
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);

Quitar participante

Use removeParticipant el método para quitar un participante del subproceso de chat. identifier es communicationIdentifier que ha creado.

chatThreadClient.removeParticipant(user);

Operaciones de recepción de lectura

Envío de confirmación de lectura

Use sendReadReceipt el método para publicar un evento de recepción de lectura en un subproceso de chat, en nombre de un usuario. chatMessageId es el identificador único del mensaje de chat que se leyó.

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

Obtención de confirmaciones de lectura

getReadReceipts el método recupera recibos de lectura para un subproceso 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()));
});

Operaciones de notificación de escritura

Envío de notificación de escritura

Use sendTypingNotification el método para publicar un evento de notificación de escritura en un subproceso de chat, en nombre de un usuario. typingNotificationOptions se usa para describir la solicitud de notificación de escritura.

  • Use senderDisplayName para establecer el nombre para mostrar del remitente de la notificación;
TypingNotificationOptions options = new TypingNotificationOptions();
options.setSenderDisplayName("Sender Display Name");
chatThreadClient.sendTypingNotificationWithResponse(options, Context.NONE);

Solución de problemas

En curso.

Pasos siguientes

Consulte otras bibliotecas cliente para El servicio de comunicación de Azure