Biblioteca cliente de Azure Web PubSub para Java

Nota:

Los detalles sobre los términos usados aquí se describen en el artículo Conceptos clave.

El SDK del lado cliente tiene como objetivo acelerar el flujo de trabajo del desarrollador; más concretamente,

• simplifica la administración de conexiones de cliente
• simplifica el envío de mensajes entre clientes
• realiza reintentos automáticos después de caídas no deseadas de la conexión de cliente
• entrega mensajes de forma confiable en número y en orden después de recuperarse de caídas de conexión

Como se muestra en el diagrama, los clientes establecen conexiones de WebSocket con el recurso de Web PubSub.

Importante

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración.

Una cadena de conexión incluye la información de autorización necesaria para que la aplicación acceda al servicio Azure Web PubSub. La clave de acceso dentro de la cadena de conexión es similar a una contraseña raíz para el servicio. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura y proteja la conexión con WebPubSubServiceClient.

Evite distribuirlas a otros usuarios, codificarlas de forma rígida o guardarlas en un archivo de texto sin formato al que puedan acceder otros usuarios. Rote sus claves si cree que se han puesto en peligro.

Introducción

Requisitos previos

• Kit de desarrollo de Java (JDK), versión 8 o posterior
• Suscripción de Azure
• Una instancia existente de Web PubSub

Adición del paquete al proyecto

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub-client</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

Autenticar el cliente

Un cliente usa una instancia de Client Access URL para conectarse al servicio y autenticarse en él. La dirección URL sigue el patrón de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Hay varias formas de obtener una instancia de Client Access URL. Como inicio rápido, puede copiar y pegar desde Azure Portal y, para producción, normalmente necesita un servidor de negociación para generar la dirección URL. Vea lo detalles.

Uso de Client Access URL desde Azure Portal

Como inicio rápido, puede ir a Azure Portal y copiar la Dirección URL de acceso de cliente desde el panel Claves.

Como se muestra en el diagrama, al cliente se le concede permiso para enviar mensajes a grupos específicos y unirse a grupos específicos. Para más información sobre el permiso de cliente, vea permisos.

WebPubSubClient client = new WebPubSubClientBuilder()
    .clientAccessUrl("<client-access-url>")
    .buildClient();

Uso del servidor de negociación para generar Client Access URL

En producción, un cliente suele capturar Client Access URL de un servidor de negociación. El servidor contiene la instancia de connection string y genera Client Access URL mediante WebPubSubServiceClient. Como ejemplo, en el fragmento de código simplemente se muestra cómo generar Client Access URL dentro de un único proceso.

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura y proteja la conexión con WebPubSubServiceClient.

// WebPubSubServiceAsyncClient is from com.azure:azure-messaging-webpubsub
// create WebPubSub service client
WebPubSubServiceAsyncClient serverClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("<hub>>")
    .buildAsyncClient();

// wrap WebPubSubServiceAsyncClient.getClientAccessToken as WebPubSubClientCredential
WebPubSubClientCredential clientCredential = new WebPubSubClientCredential(Mono.defer(() ->
    serverClient.getClientAccessToken(new GetClientAccessTokenOptions()
            .setUserId("<user-name>")
            .addRole("webpubsub.joinLeaveGroup")
            .addRole("webpubsub.sendToGroup"))
        .map(WebPubSubClientAccessToken::getUrl)));

// create WebPubSub client
WebPubSubClient client = new WebPubSubClientBuilder()
    .credential(clientCredential)
    .buildClient();

Características para diferenciar WebPubSubClient y WebPubSubServiceClient.

Class Name (Nombre de clase)	WebPubSubClient	WebPubSubServiceClient
Nombre del paquete	azure-messaging-webpubsub-client	azure-messaging-webpubsub
Características	Se usa en el lado cliente. Publicación y suscripción a mensajes.	Se usa en el lado de servidor. Genere Client Access URL y administre clientes.

Ejemplos

Consumo de mensajes del servidor y los grupos

Un cliente puede agregar devoluciones de llamada para consumir mensajes del servidor y los grupos. Tenga en cuenta que los clientes solo pueden recibir mensajes del grupo al que se hayan unido.

client.addOnGroupMessageEventHandler(event -> {
    System.out.println("Received group message from " + event.getFromUserId() + ": "
        + event.getData().toString());
});
client.addOnServerMessageEventHandler(event -> {
    System.out.println("Received server message: "
        + event.getData().toString());
});

Adición de devoluciones de llamada para eventos connected, disconnectedy stopped

Cuando una conexión de cliente está conectada al servicio, se desencadena el evento connected.

Cuando se desconecta una conexión de cliente y no se puede recuperar, se desencadena el evento disconnected.

Cuando se detiene un cliente, lo que significa que la conexión de cliente se ha desconectado y el cliente deja de intentar volver a conectarse, se desencadena el evento stopped. Esto suele ocurrir después de llamar a client.StopAsync() o deshabilitar AutoReconnect. Si quiere reiniciar el cliente, puede llamar a client.StartAsync() en el evento Stopped.

client.addOnConnectedEventHandler(event -> {
    System.out.println("Connection is connected: " + event.getConnectionId());
});
client.addOnDisconnectedEventHandler(event -> {
    System.out.println("Connection is disconnected");
});
client.addOnStoppedEventHandler(event -> {
    System.out.println("Client is stopped");
});

Operación y reintento

De manera predeterminada, la operación, como client.joinGroup(), client.leaveGroup(), client.sendToGroup() o client.sendEvent(), tiene tres reintentos. Puede usar WebPubSubClientBuilder.retryOptions() para cambiarlo. Si se han producido errores en todos los reintentos, se produce un error. Puede seguir intentando si pasa el mismo valor ackId que en los reintentos anteriores, por lo que el servicio puede ayudar a desduplicar la operación con el mismo valor ackId.

try {
    client.joinGroup("testGroup");
} catch (SendMessageFailedException e) {
    if (e.getAckId() != null) {
        client.joinGroup("testGroup", e.getAckId());
    }
}

Solución de problemas

Habilitamiento de registros

Puede establecer la siguiente variable de entorno para obtener los registros de depuración cuando se usa esta biblioteca.

export AZURE_LOG_LEVEL=verbose

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Seguimiento en vivo

Use la herramienta Live Trace de Azure Portal para inspeccionar el tráfico de mensajes en directo por medio del recurso de Web PubSub.