Libreria client WebPubSub di Azure per Java

L'SDK lato client mira a velocizzare il flusso di lavoro dello sviluppatore; più in particolare,

• semplifica la gestione delle connessioni client
• semplifica l'invio di messaggi tra i client
• tentativi automatici dopo l'eliminazione imprevista della connessione client
• recapita in modo affidabile i messaggi in numero e in ordine dopo il ripristino dall'eliminazione della connessione

Come illustrato nel diagramma, i client stabiliscono connessioni WebSocket con la risorsa Web PubSub.

Introduzione

Prerequisiti

• Java Development Kit (JDK) versione 8 o successiva
• Sottoscrizione di Azure
• Un'istanza Web PubSub esistente

Aggiunta del pacchetto al prodotto

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

Autenticare il client

Un client usa un Client Access URL oggetto per connettersi ed eseguire l'autenticazione con il servizio. L'URL segue un modello di wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Esistono diversi modi per ottenere un oggetto Client Access URL. Come avvio rapido, è possibile copiare e incollare da portale di Azure e per la produzione, in genere è necessario un server di negoziazione per generare l'URL. Vedi i dettagli.

Usare Client Access URL da portale di Azure

Come guida introduttiva, è possibile passare a portale di Azure e copiare l'URL accesso client dal pannello Chiavi.

Come illustrato nel diagramma, al client viene concessa l'autorizzazione per l'invio di messaggi a gruppi specifici e l'aggiunta a gruppi specifici. Altre informazioni sull'autorizzazione client, vedere Autorizzazioni.

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

Usare il server di negoziazione per generare Client Access URL

Nell'ambiente di produzione, un client recupera in genere l'oggetto Client Access URL da un server di negoziazione. Il server contiene connection string e genera l'oggetto Client Access URL tramite WebPubSubServiceClient. Come esempio, il frammento di codice illustra semplicemente come generare l'oggetto Client Access URL all'interno di un singolo processo.

Le stringa di connessione non elaborate vengono visualizzate in questo articolo solo a scopo dimostrativo. Negli ambienti di produzione proteggere sempre le chiavi di accesso. Usare Azure Key Vault per gestire e ruotare le chiavi in modo sicuro e proteggere la connessione 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();

Funzionalità per distinguere WebPubSubClient e WebPubSubServiceClient.

Esempi

Utilizzare messaggi dal server e dai gruppi

Un client può aggiungere callback per utilizzare messaggi dal server e dai gruppi. Si noti che i client possono ricevere solo messaggi di gruppo aggiunti.

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

Aggiungere callback per connectedgli eventi , disconnectede stopped

Quando una connessione client è connessa al servizio, l'evento connected viene attivato.

Quando una connessione client viene disconnessa e non riesce a eseguire il ripristino, l'evento disconnected viene attivato.

Quando un client viene arrestato, il che significa che la connessione client viene disconnessa e il client smette di tentare di riconnettersi, l'evento stopped viene attivato. Ciò si verifica in genere dopo la client.StopAsync() chiamata o la disabilita.AutoReconnect Se si vuole riavviare il client, è possibile chiamare client.StartAsync() nell'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");
});

Operazione e ripetizione dei tentativi

Per impostazione predefinita, l'operazione come client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() ha tre reti. È possibile usare WebPubSubClientBuilder.retryOptions() per modificare. Se tutti i tentativi non sono riusciti, viene generato un errore. È possibile continuare a ripetere i tentativi passando gli stessi ackId tentativi precedenti, pertanto il servizio può aiutare a deduplicare l'operazione con lo stesso ackId.

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

Risoluzione dei problemi

Abilitare i log

È possibile impostare la variabile di ambiente seguente per ottenere i log di debug quando si usa questa libreria.

export AZURE_LOG_LEVEL=verbose

Per istruzioni più dettagliate su come abilitare i log, vedere la documentazione sul pacchetto @azure/logger.

Traccia in tempo reale

Usare lo strumento Live Trace da portale di Azure per esaminare il traffico dei messaggi live attraverso la risorsa Web PubSub.