Biblioteka klienta Azure WebPubSub dla języka Java

Uwaga

Szczegółowe informacje na temat terminów używanych w tym miejscu opisano w artykule dotyczącym kluczowych pojęć.

Zestaw SDK po stronie klienta ma na celu przyspieszenie przepływu pracy dewelopera; w szczególności,

• upraszcza zarządzanie połączeniami klientów
• upraszcza wysyłanie komunikatów między klientami
• automatyczne ponawianie próby po niezamierzonych spadkach połączenia klienta
• niezawodne dostarczanie komunikatów o numerze i w kolejności po odzyskaniu po spadku połączenia

Jak pokazano na diagramie, klienci ustanawiają połączenia protokołu WebSocket z zasobem Web PubSub.

Ważne

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych.

Parametry połączenia zawiera informacje o autoryzacji wymagane przez aplikację w celu uzyskania dostępu do usługi Azure Web PubSub. Klucz dostępu wewnątrz parametry połączenia jest podobny do hasła głównego usługi. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Użyj usługi Azure Key Vault, aby bezpiecznie zarządzać kluczami i obracać je oraz zabezpieczać połączenie za pomocą usługi WebPubSubServiceClient.

Unikaj dystrybuowania kluczy dostępu do innych użytkowników, kodowania ich lub zapisywania ich w dowolnym miejscu w postaci zwykłego tekstu, który jest dostępny dla innych użytkowników. Obracanie kluczy, jeśli uważasz, że mogły one zostać naruszone.

Wprowadzenie

Wymagania wstępne

• Zestaw Java Development Kit (JDK) w wersji 8 lub nowszej
• Subskrypcja platformy Azure
• Istniejące wystąpienie usługi Web PubSub

Dodawanie pakietu do produktu

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

Uwierzytelnianie użytkownika

Klient używa metody do Client Access URL nawiązywania połączenia i uwierzytelniania za pomocą usługi. Adres URL jest zgodny ze wzorcem .wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token> Istnieje wiele sposobów uzyskania .Client Access URL W ramach szybkiego startu można kopiować i wklejać z witryny Azure Portal, a w środowisku produkcyjnym zwykle potrzebny jest serwer negocjacji w celu wygenerowania adresu URL. Zobacz szczegółowe informacje.

Korzystanie Client Access URL z witryny Azure Portal

W ramach szybkiego startu możesz przejść do witryny Azure Portal i skopiować adres URL dostępu klienta z bloku Klucze .

Jak pokazano na diagramie, klient ma uprawnienie do wysyłania komunikatów do określonych grup i dołączania do określonych grup. Dowiedz się więcej o uprawnieniach klienta, zobacz uprawnienia.

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

Generowanie przy użyciu serwera negocjacji Client Access URL

W środowisku produkcyjnym klient zwykle pobiera element Client Access URL z serwera negocjacji. Serwer przechowuje element connection string i generuje element Client Access URL za pomocą polecenia WebPubSubServiceClient. Jako przykład fragment kodu pokazuje, jak wygenerować Client Access URL wewnątrz jednego procesu.

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Użyj usługi Azure Key Vault, aby bezpiecznie zarządzać kluczami i obracać je oraz zabezpieczać połączenie za pomocą usługi 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();

Funkcje do rozróżniania WebPubSubClient i WebPubSubServiceClient.

Nazwa klasy	WebPubSubClient	WebPubSubServiceClient
Nazwa pakietu	azure-messaging-webpubsub-client	azure-messaging-webpubsub
Funkcje	Używane po stronie klienta. Publikowanie komunikatów i subskrybowanie wiadomości.	Używane po stronie serwera. Generowanie Client Access URL klientów i zarządzanie nimi.

Przykłady

Korzystanie z komunikatów z serwera i grup

Klient może dodać wywołania zwrotne w celu korzystania z komunikatów z serwera i grup. Należy pamiętać, że klienci mogą odbierać tylko sprzężone komunikaty grupowe.

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

Dodawanie wywołań zwrotnych dla connectedzdarzeń , disconnectedi stopped

Gdy połączenie klienta jest połączone z usługą, connected zdarzenie jest wyzwalane.

Gdy połączenie klienta zostanie rozłączone i nie można go odzyskać, disconnected zdarzenie zostanie wyzwolone.

Gdy klient zostanie zatrzymany, co oznacza, że połączenie klienta zostanie rozłączone, a klient przestanie próbować ponownie nawiązać połączenie, stopped zdarzenie jest wyzwalane. Dzieje się tak zwykle po wywołaniu lub wyłączeniu client.StopAsync()AutoReconnect. Jeśli chcesz ponownie uruchomić klienta, możesz wywołać client.StartAsync() to Stopped zdarzenie.

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

Operacja i ponów próbę

Domyślnie operacja taka jak client.joinGroup(), client.leaveGroup(), client.sendToGroup()client.sendEvent() ma trzy reties. Możesz użyć WebPubSubClientBuilder.retryOptions() polecenia , aby zmienić. Jeśli wszystkie ponowne próby nie powiodły się, zostanie zgłoszony błąd. Ponów próbę można zachować, przekazując te same ackId próby co poprzednie ponawianie prób, dzięki czemu usługa może pomóc w deduplikacji operacji przy użyciu tego samego ackIdelementu .

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

Rozwiązywanie problemów

Włączanie dzienników

Możesz ustawić następującą zmienną środowiskową, aby pobrać dzienniki debugowania podczas korzystania z tej biblioteki.

export AZURE_LOG_LEVEL=verbose

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Śledzenie na żywo

Użyj narzędzia Live Trace z witryny Azure Portal, aby sprawdzić ruch komunikatów na żywo za pośrednictwem zasobu Web PubSub.