Pustaka klien Azure WebPubSub untuk Java

Catatan

Detail tentang istilah yang digunakan di sini dijelaskan dalam artikel konsep utama.

SDK sisi klien bertujuan untuk mempercepat alur kerja pengembang; lebih spesifik,

• menyederhanakan pengelolaan koneksi klien
• menyederhanakan pengiriman pesan di antara klien
• secara otomatis mencoba kembali setelah penurunan koneksi klien yang tidak diinginkan
• dengan andal mengirimkan pesan dalam jumlah dan secara berurutan setelah pulih dari penurunan koneksi

Seperti yang ditunjukkan dalam diagram, klien Anda membuat koneksi WebSocket dengan sumber daya Web PubSub Anda.

Penting

String koneksi mentah muncul dalam artikel ini hanya untuk tujuan demonstrasi.

String koneksi menyertakan informasi otorisasi yang diperlukan agar aplikasi Anda mengakses layanan Azure Web PubSub. Kunci akses di dalam string koneksi mirip dengan kata sandi root untuk layanan Anda. Di lingkungan produksi, selalu lindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman dan mengamankan koneksi Anda dengan WebPubSubServiceClient.

Hindari mendistribusikan kunci akses ke pengguna lain, melakukan hard-coding, atau menyimpannya di mana saja dalam teks biasa yang dapat diakses orang lain. Putar kunci Anda jika Anda yakin bahwa kunci tersebut mungkin telah disusupi.

Memulai

Prasyarat

• Java Development Kit (JDK) versi 8 atau lebih tinggi
• Langganan Azure
• Instans Web PubSub yang ada

Menambahkan paket ke produk Anda

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

Mengautentikasi klien

Klien menggunakan Client Access URL untuk menyambungkan dan mengautentikasi dengan layanan. URL mengikuti pola wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Ada beberapa cara untuk mendapatkan Client Access URL. Sebagai mulai cepat, Anda dapat menyalin dan menempel dari portal Azure, dan untuk produksi, Anda biasanya memerlukan server negosiasi untuk menghasilkan URL. Lihat detailnya.

Gunakan Client Access URL dari portal Azure

Sebagai mulai cepat, Anda dapat membuka portal Azure dan menyalin URL Akses Klien dari bilah Kunci.

Seperti yang ditunjukkan dalam diagram, klien diberikan izin untuk mengirim pesan ke grup tertentu dan bergabung dengan grup tertentu. Pelajari selengkapnya tentang izin klien, lihat izin.

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

Menggunakan server negosiasi untuk menghasilkan Client Access URL

Dalam produksi, klien biasanya mengambil Client Access URL dari server negosiasi. Server menyimpan connection string dan menghasilkan Client Access URL melalui WebPubSubServiceClient. Sebagai sampel, cuplikan kode hanya menunjukkan cara menghasilkan Client Access URL dalam satu proses.

String koneksi mentah muncul dalam artikel ini hanya untuk tujuan demonstrasi. Di lingkungan produksi, selalu lindungi kunci akses Anda. Gunakan Azure Key Vault untuk mengelola dan memutar kunci Anda dengan aman dan mengamankan koneksi Anda dengan 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();

Fitur untuk membedakan WebPubSubClient dan WebPubSubServiceClient.

Nama Kelas	WebPubSubClient	WebPubSubServiceClient
Nama Paket	azure-messaging-webpubsub-client	azure-messaging-webpubsub
Fitur	Digunakan di sisi klien. Terbitkan pesan dan berlangganan pesan.	Digunakan di sisi server. Membuat Client Access URL dan mengelola klien.

Contoh

Mengonsumsi pesan dari server dan grup

Klien dapat menambahkan panggilan balik untuk menggunakan pesan dari server dan grup. Perhatikan, klien hanya dapat menerima pesan grup yang telah bergabung.

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

Menambahkan panggilan balik untuk connected, disconnected, dan stopped peristiwa

Saat koneksi klien tersambung ke layanan, connected peristiwa dipicu.

Ketika koneksi klien terputus dan gagal pulih, disconnected peristiwa dipicu.

Ketika klien dihentikan, yang berarti koneksi klien terputus dan klien berhenti mencoba menyambungkan kembali, stopped peristiwa dipicu. Ini biasanya terjadi setelah dipanggil client.StopAsync() , atau dinonaktifkan AutoReconnect. Jika Anda ingin menghidupkan ulang klien, Anda dapat memanggil client.StartAsync() dalam peristiwa tersebut 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");
});

Operasi dan coba lagi

Secara default, operasi seperti client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() memiliki tiga percobaan ulang. Anda dapat menggunakan WebPubSubClientBuilder.retryOptions() untuk mengubah. Jika semua percobaan ulang gagal, kesalahan akan muncul. Anda dapat terus mencoba kembali dengan meneruskan hal yang sama ackId seperti percobaan ulang sebelumnya, sehingga layanan dapat membantu mendeduplikasi operasi dengan yang sama ackId.

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

Pemecahan Masalah

Aktifkan Log

Anda dapat mengatur variabel lingkungan berikut untuk mendapatkan log debug saat menggunakan pustaka ini.

export AZURE_LOG_LEVEL=verbose

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

Jejak Hidup

Gunakan alat Live Trace dari portal Azure untuk memeriksa lalu lintas pesan langsung melalui sumber daya Web PubSub Anda.