Klientská knihovna Azure WebPubSub pro Javu

Poznámka:

Podrobnosti o zde použitých termínech jsou popsány v klíčovém článku o konceptech .

Cílem sady SDK na straně klienta je urychlit pracovní postup vývojáře; konkrétněji,

• zjednodušuje správu klientských připojení.
• zjednodušuje odesílání zpráv mezi klienty.
• automatické opakování po nezamýšlených poklesech připojení klienta
• spolehlivé doručování zpráv v čísle a v pořadí po obnovení z výpadků připojení

Jak je znázorněno v diagramu, vaši klienti navazují připojení WebSocket s prostředkem Web PubSub.

Důležité

Nezpracované připojovací řetězec se v tomto článku zobrazují jenom pro demonstrační účely.

Připojovací řetězec obsahuje informace o autorizaci vyžadované pro vaši aplikaci pro přístup ke službě Azure Web PubSub. Přístupový klíč uvnitř připojovací řetězec je podobný kořenovému heslu pro vaši službu. V produkčních prostředích vždy chraňte přístupové klíče. Pomocí služby Azure Key Vault můžete bezpečně spravovat a obměňovat klíče a zabezpečit připojení WebPubSubServiceClient.

Vyhněte se distribuci přístupových klíčů ostatním uživatelům, jejich pevnému kódování nebo jejich uložení kdekoli ve formátu prostého textu, který je přístupný ostatním uživatelům. Otočte klíče, pokud se domníváte, že mohly být ohroženy.

Začínáme

Požadavky

• Java Development Kit (JDK) verze 8 nebo novější
• Předplatné Azure
• Existující instance Web PubSub

Přidání balíčku do produktu

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

Ověření klienta

Klient se ke Client Access URL službě připojuje a ověřuje. Adresa URL se řídí vzorem wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Existuje několik způsobů, jak získat Client Access URL. Jako rychlý start můžete kopírovat a vkládat z webu Azure Portal a pro produkční prostředí obvykle potřebujete k vygenerování adresy URL server vyjednávání. Viz podrobnosti.

Použití Client Access URL na webu Azure Portal

Jako rychlý start můžete přejít na Web Azure Portal a zkopírovat adresu URL klientského přístupu z okna Klíče.

Jak je znázorněno v diagramu, klientovi je uděleno oprávnění k odesílání zpráv konkrétním skupinám a připojování ke konkrétním skupinám. Další informace o oprávněních klienta najdete v tématu Oprávnění.

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

Generování pomocí serveru vyjednávání Client Access URL

V produkčním prostředí klient obvykle načte Client Access URL server vyjednávání. Server uchovává connection string a generuje Client Access URL prostřednictvím WebPubSubServiceClient. Jako příklad fragment kódu ukazuje, jak vygenerovat Client Access URL uvnitř jednoho procesu.

Nezpracované připojovací řetězec se v tomto článku zobrazují jenom pro demonstrační účely. V produkčních prostředích vždy chraňte přístupové klíče. Pomocí služby Azure Key Vault můžete bezpečně spravovat a obměňovat klíče a zabezpečit připojení 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();

Funkce pro rozlišení WebPubSubClient a WebPubSubServiceClient.

Název třídy	WebPubSubClient	WebPubSubServiceClient
Název balíčku	azure-messaging-webpubsub-client	azure-messaging-webpubsub
Funkce	Používá se na straně klienta. Publikování zpráv a přihlášení k odběru zpráv	Používá se na straně serveru. Generování Client Access URL a správa klientů

Příklady

Využívání zpráv ze serveru a skupin

Klient může přidat zpětná volání pro využívání zpráv ze serveru a skupin. Upozorňujeme, že klienti můžou přijímat jenom zprávy skupiny, ke kterým se připojil.

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

Přidání zpětných volání pro connected, disconnecteda stopped událostí

Když je připojení klienta ke službě připojené, connected aktivuje se událost.

Když se připojení klienta odpojí a nepodaří se obnovit, disconnected aktivuje se událost.

Když je klient zastavený, což znamená, že je připojení klienta odpojené a klient se přestane pokoušet znovu připojit, stopped aktivuje se událost. K tomu obvykle dochází po client.StopAsync() zavolání nebo zakázání AutoReconnect. Pokud chcete klienta restartovat, můžete zavolat client.StartAsync() v Stopped události.

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

Operace a opakování

Ve výchozím nastavení má operace, například client.joinGroup(), client.leaveGroup()client.sendToGroup()client.sendEvent() , tři reties. Můžete použít WebPubSubClientBuilder.retryOptions() ke změně. Pokud došlo k selhání všech opakovaných pokusů, vyvolá se chyba. Opakování můžete pokračovat předáním stejného ackId opakování jako v předchozích opakováních, takže služba může pomoct odstranit operaci se stejným ackId.

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

Řešení problému

Povolení protokolů

Následující proměnnou prostředí můžete nastavit tak, aby při používání této knihovny získala protokoly ladění.

export AZURE_LOG_LEVEL=verbose

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Živé trasování

Pomocí nástroje Živé trasování z webu Azure Portal můžete kontrolovat provoz živých zpráv prostřednictvím prostředku Web PubSub.