Azure WebPubSub ügyfélkódtár Java-hoz

Feljegyzés

Az itt használt kifejezések részleteit a fő fogalmakról szóló cikk ismerteti.

Az ügyféloldali SDK célja a fejlesztői munkafolyamat felgyorsítása; pontosabban,

• leegyszerűsíti az ügyfélkapcsolatok kezelését
• leegyszerűsíti az üzenetek küldését az ügyfelek között
• automatikus újrapróbálkozás az ügyfélkapcsolat nem tervezett megszakadása után
• megbízhatóan kézbesíti az üzeneteket számban és sorrendben a kapcsolat megszakadása utáni helyreállítás után

Ahogy a diagramon látható, az ügyfelek WebSocket-kapcsolatokat létesítenek a Web PubSub-erőforrással.

Fontos

A cikkben szereplő nyers kapcsolati sztring csak bemutató célokra jelennek meg.

A kapcsolati sztring tartalmazzák azokat az engedélyezési információkat, amelyekre az alkalmazásnak szüksége van az Azure Web PubSub szolgáltatás eléréséhez. A kapcsolati sztring belüli hozzáférési kulcs hasonló a szolgáltatás gyökérjelszójához. Éles környezetben mindig védje a hozzáférési kulcsokat. Az Azure Key Vault használatával biztonságosan kezelheti és elforgathatja a kulcsokat, és biztonságossá teheti a kapcsolatot.WebPubSubServiceClient

Kerülje a hozzáférési kulcsok más felhasználók számára való terjesztését, a szigorú kódolást, illetve a mások számára hozzáférhető egyszerű szövegek mentését. Ha úgy véli, hogy illetéktelenek lettek, forgassa el a kulcsokat.

Első lépések

Előfeltételek

• A Java fejlesztői készlet (JDK) 8-as vagy újabb verziója
• Azure-előfizetés
• Meglévő Web PubSub-példány

A csomag hozzáadása a termékhez

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

Az ügyfél hitelesítése

Az ügyfél a szolgáltatással való csatlakozáshoz és hitelesítéshez használ egy ügyfelet Client Access URL . Az URL-cím a következő mintát wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>követi: . Többféleképpen is lekérheti a Client Access URL. Első lépésként másolhatja és beillesztheti az Azure Portalról, és éles környezetben általában egy egyeztetési kiszolgálóra van szüksége az URL-cím létrehozásához. Részletek megtekintése.

Használat Client Access URL az Azure Portalról

Első lépésként nyissa meg az Azure Portalt, és másolja az ügyfélelérési URL-címet a Kulcsok panelről.

A diagramon látható módon az ügyfél engedélyt kap arra, hogy üzeneteket küldjön adott csoportoknak, és egyes csoportokhoz csatlakozzon. További információ az ügyfélengedélyekről, lásd az engedélyeket.

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

A tárgyalási kiszolgáló használata a létrehozáshoz Client Access URL

Éles környezetben az ügyfél általában lekéri a Client Access URL tárgyalási kiszolgálóról. A kiszolgáló tárolja a kiszolgálót connection string , és létrehozza a Client Access URL rajta keresztüli WebPubSubServiceClientelemet. Mintaként a kódrészlet bemutatja, hogyan hozhat létre Client Access URL egy folyamaton belül.

A cikkben szereplő nyers kapcsolati sztring csak bemutató célokra jelennek meg. Éles környezetben mindig védje a hozzáférési kulcsokat. Az Azure Key Vault használatával biztonságosan kezelheti és elforgathatja a kulcsokat, és biztonságossá teheti a kapcsolatot.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();

A megkülönböztetni és WebPubSubClientmegkülönböztetni WebPubSubServiceClient kívánt funkciók.

Osztály neve	WebPubSubClient	WebPubSubServiceClient
Csomag neve	azure-messaging-webpubsub-client	azure-messaging-webpubsub
Funkciók	Ügyféloldalon használatos. Üzenetek közzététele és feliratkozás az üzenetekre.	Kiszolgálóoldalon használható. Ügyfelek létrehozása Client Access URL és kezelése.

Példák

Üzenetek felhasználása a kiszolgálóról és a csoportokból

Az ügyfél visszahívásokat adhat hozzá a kiszolgálótól és a csoportoktól érkező üzenetek felhasználásához. Vegye figyelembe, hogy az ügyfelek csak olyan csoportos üzeneteket fogadhatnak, amelyekhez csatlakozott.

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

Visszahívások hozzáadása a , connectedés disconnected eseményekhez stopped

Amikor egy ügyfélkapcsolat csatlakozik a szolgáltatáshoz, az connected esemény aktiválódik.

Ha egy ügyfélkapcsolat megszakad, és nem áll helyre, az disconnected esemény aktiválódik.

Ha egy ügyfél leáll, ami azt jelenti, hogy az ügyfélkapcsolat megszakad, és az ügyfél nem próbál újracsatlakozni, az stopped esemény aktiválódik. Ez általában akkor fordul elő, ha a client.StopAsync() rendszer meghívja vagy letiltja a parancsot AutoReconnect. Ha újra szeretné indítani az ügyfelet, meghívhatja client.StartAsync() az eseményt 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");
});

Művelet és újrapróbálkozás

Alapértelmezés szerint az olyan művelet, mint client.joinGroup()a , client.leaveGroup()client.sendToGroup()három client.sendEvent() reties. A módosítást használhatja WebPubSubClientBuilder.retryOptions() . Ha az összes újrapróbálkozás sikertelen volt, hiba jelenik meg. Az újrapróbálkozást az előző újrapróbálkozással megegyező ackId módon végezheti el, így a szolgáltatás segíthet a művelet deduplikációjában ugyanazzal ackIda művelettel.

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

Hibaelhárítás

Naplók engedélyezése

A következő környezeti változóval lekérheti a hibakeresési naplókat a kódtár használatakor.

export AZURE_LOG_LEVEL=verbose

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

Élő nyomkövetés

Az Azure Portal élő nyomkövetési eszközével élő üzenetforgalmat vizsgálhat meg a Web PubSub-erőforráson keresztül.