Azure WebPubSub-klientbibliotek för Java

SDK:et på klientsidan syftar till att påskynda utvecklarens arbetsflöde. mer specifikt,

• förenklar hanteringen av klientanslutningar
• förenklar sändning av meddelanden mellan klienter
• försöker automatiskt igen efter oavsiktliga droppar av klientanslutningen
• levererar tillförlitligt meddelanden i antal och i ordning efter att anslutningen har återställts

Som du ser i diagrammet upprättar klienterna WebSocket-anslutningar med din Web PubSub-resurs.

Komma igång

Förutsättningar

• Java Development Kit (JDK) med version 8 eller senare
• Azure-prenumeration
• En befintlig Web PubSub-instans

Lägga till paketet i din produkt

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

Autentisera klienten

En klient använder en Client Access URL för att ansluta och autentisera med tjänsten. URL:en följer ett mönster med wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Det finns flera sätt att hämta en Client Access URL. Som en snabbstart kan du kopiera och klistra in från Azure Portal, och för produktion behöver du vanligtvis en förhandlingsserver för att generera URL:en. Se information.

Använd Client Access URL från Azure Portal

Som en snabbstart kan du gå till Azure Portal och kopiera URL:en för klientåtkomst från bladet Nycklar.

Som du ser i diagrammet beviljas klienten behörighet att skicka meddelanden till specifika grupper och ansluta till specifika grupper. Mer information om klientbehörighet finns i behörigheter.

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

Använda förhandlingsservern för att generera Client Access URL

I produktion hämtar Client Access URL en klient vanligtvis från en förhandlingsserver. Servern innehåller connection string och genererar Client Access URL via WebPubSubServiceClient. Som ett exempel visar kodfragmentet bara hur du genererar Client Access URL inuti en enda process.

Råa anslutningssträng visas endast i den här artikeln i demonstrationssyfte. Skydda alltid dina åtkomstnycklar i produktionsmiljöer. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt och skydda anslutningen med 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();

Funktioner för att särskilja WebPubSubClient och WebPubSubServiceClient.

Exempel

Använda meddelanden från servern och grupperna

En klient kan lägga till återanrop för att använda meddelanden från servern och grupperna. Observera att klienter bara kan ta emot gruppmeddelanden som har anslutits.

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

Lägga till återanrop för connected, disconnectedoch stopped händelser

När en klientanslutning är ansluten till tjänsten connected utlöses händelsen.

När en klientanslutning kopplas från och inte kan återställas disconnected utlöses händelsen.

När en klient stoppas, vilket innebär att klientanslutningen är frånkopplad och klienten slutar försöka återansluta, stopped utlöses händelsen. Detta inträffar vanligtvis efter att client.StopAsync() anropas eller inaktiverats AutoReconnect. Om du vill starta om klienten kan du anropa client.StartAsync() händelsen 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");
});

Åtgärd och försök igen

Som standard har åtgärden client.joinGroup(), , client.leaveGroup()client.sendToGroup(), client.sendEvent() tre återställningar. Du kan använda WebPubSubClientBuilder.retryOptions() för att ändra. Om alla återförsök har misslyckats utlöses ett fel. Du kan fortsätta att försöka igen genom att skicka in samma ackId som tidigare återförsök, så tjänsten kan hjälpa till att deduplicera åtgärden med samma ackId.

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

Felsökning

Aktivera loggar

Du kan ange följande miljövariabel för att hämta felsökningsloggarna när du använder det här biblioteket.

export AZURE_LOG_LEVEL=verbose

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Livespårning

Använd livespårningsverktyget från Azure Portal för att inspektera livemeddelandetrafik via din Web PubSub-resurs.