Bagikan melalui

Pustaka klien Web PubSub untuk JavaScript

azure Web PubSub adalah layanan cloud yang membantu pengembang dengan mudah membangun fitur real-time di aplikasi web dengan pola terbitkan-berlangganan dalam skala besar.

Skenario apa pun yang memerlukan olahpesan real-time antara server dan klien atau di antara klien yang mengikuti pola terbitkan-berlangganan dapat memperoleh manfaat dari menggunakan Web PubSub. Pengembang tidak perlu lagi melakukan polling server dengan mengirim permintaan HTTP berulang pada interval, yang boros dan sulit diskalakan.

Seperti yang ditunjukkan pada diagram di bawah ini, klien Anda membuat koneksi WebSocket dengan sumber daya Web PubSub Anda. Pustaka klien ini:

  • 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

Detail tentang istilah yang digunakan di sini dijelaskan di bagian konsep utama.

Pustaka ini dihosting di NPM.

Persiapan

Lingkungan yang saat ini didukung

Prasyarat

1. Instal paket @azure/web-pubsub-client

npm install @azure/web-pubsub-client

2. Sambungkan dengan sumber daya Web PubSub Anda

Klien menggunakan URL Akses Klien untuk menyambungkan dan mengautentikasi dengan layanan, yang mengikuti pola wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Klien dapat memiliki beberapa cara untuk mendapatkan URL Akses Klien. Untuk mulai cepat ini, Anda dapat menyalin dan menempelkannya dari Portal Microsoft Azure yang ditunjukkan di bawah ini. (Untuk produksi, klien Anda biasanya mendapatkan URL Akses Klien yang dibuat di server aplikasi Anda. Lihat detail di bawah ini )

get_client_url

Seperti yang ditunjukkan pada diagram di atas, klien memiliki izin untuk mengirim pesan ke dan bergabung dengan grup tertentu bernama "group1".

// Imports the client libray
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. Bergabung dengan grup

Perhatikan bahwa klien hanya dapat menerima pesan dari grup yang telah bergabung dan Anda perlu menambahkan panggilan balik untuk menentukan logika saat menerima pesan.

// ...continues the code snippet from above

// Specifies the group to join
const groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. Mengirim pesan ke grup

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

Contoh

Menambahkan panggilan balik untuk peristiwa yang tersambung, terputus, dan dihentikan

  1. Ketika klien berhasil terhubung ke sumber daya Web PubSub Anda, peristiwa connected dipicu.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Ketika klien terputus dan gagal memulihkan koneksi, peristiwa disconnected dipicu.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. Peristiwa stopped akan dipicu ketika klien terputus dan klien berhenti mencoba menyambungkan kembali. Ini biasanya terjadi setelah client.stop() dipanggil, atau autoReconnect dinonaktifkan atau batas yang ditentukan untuk mencoba menyambungkan kembali telah tercapai. Jika Anda ingin memulai ulang klien, Anda dapat memanggil client.start() dalam peristiwa yang dihentikan.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Menggunakan server negosiasi untuk menghasilkan URL Akses Klien secara terprogram

Dalam produksi, klien biasanya mengambil URL Akses Klien dari server aplikasi. Server menyimpan string koneksi ke sumber daya Web PubSub Anda dan menghasilkan URL Akses Klien dengan bantuan dari pustaka server @azure/web-pubsub.

1. Server aplikasi

Cuplikan kode di bawah ini adalah contoh server aplikasi yang mengekspos jalur /negotiate dan mengembalikan URL Akses Klien.

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  const token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. Sisi klien

Cuplikan kode di bawah ini adalah contoh sisi klien.

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    const value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

Untuk melihat kode lengkap sampel ini, silakan lihat samples-browser.

Klien menggunakan pesan dari server aplikasi atau grup yang bergabung

Klien dapat menambahkan panggilan balik untuk menggunakan pesan dari server atau grup aplikasi Anda. Harap dicatat, untuk peristiwa group-message, klien hanya dapat menerima pesan grup yang telah bergabung.

// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

Menangani kegagalan bergabung kembali

Ketika klien terputus dan gagal pulih, semua konteks grup akan dibersihkan di sumber daya Web PubSub Anda. Ini berarti ketika klien terhubung kembali, klien perlu bergabung kembali dengan grup. Secara default, klien memiliki opsi autoRejoinGroup diaktifkan.

Namun, Anda harus menyadari batasan autoRejoinGroup.

  • Klien hanya dapat bergabung kembali dengan grup yang awalnya bergabung dengan kode klien tidak oleh kode sisi server.
  • Operasi "bergabung kembali dengan grup" mungkin gagal karena berbagai alasan, misalnya klien tidak memiliki izin untuk bergabung dengan grup. Dalam kasus seperti itu, Anda perlu menambahkan panggilan balik untuk menangani kegagalan ini.
// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

Operasi dan coba lagi

Secara default, operasi seperti client.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() memiliki tiga percobaan ulang. Anda dapat mengonfigurasi melalui messageRetryOptions. Jika semua percobaan ulang gagal, kesalahan akan dilemparkan. Anda dapat terus mencoba kembali dengan meneruskan ackId yang sama dengan percobaan ulang sebelumnya sehingga layanan Web PubSub dapat mendeduplikasi operasi.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

Tentukan subprotoklasi

Anda dapat mengubah subprotokul yang akan digunakan oleh klien. Secara default, klien menggunakan json.reliable.webpubsub.azure.v1. Anda dapat memilih untuk menggunakan json.reliable.webpubsub.azure.v1 atau json.webpubsub.azure.v1.

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonProtocol() });

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonReliableProtocol() });

Konsep utama

Sambungan

Koneksi, juga dikenal sebagai klien atau koneksi klien, mewakili koneksi WebSocket individual yang terhubung ke Web PubSub. Ketika berhasil tersambung, ID koneksi unik ditetapkan ke koneksi ini oleh Web PubSub. Setiap WebPubSubClient menciptakan koneksi eksklusifnya sendiri.

Pemulihan

Jika klien yang menggunakan protokol andal terputus, WebSocket baru mencoba membuat menggunakan ID koneksi koneksi yang hilang. Jika koneksi WebSocket baru berhasil tersambung, koneksi akan dipulihkan. Sepanjang waktu klien terputus, layanan mempertahankan konteks klien serta semua pesan yang berlangganan klien, dan ketika klien pulih, layanan akan mengirim pesan ini ke klien. Jika layanan mengembalikan kode kesalahan WebSocket 1008 atau upaya pemulihan berlangsung lebih dari 30 detik, pemulihan gagal.

Sambungkan ulang

Koneksi ulang terjadi ketika koneksi klien terputus dan gagal pulih. Koneksi ulang memulai koneksi baru dan koneksi baru memiliki ID koneksi baru. Tidak seperti pemulihan, layanan memperlakukan klien yang terhubung kembali sebagai koneksi klien baru. Koneksi klien perlu bergabung kembali dengan grup. Secara default, pustaka klien bergabung kembali dengan grup setelah koneksi ulang.

Hub

Hub adalah konsep logis untuk sekumpulan koneksi klien. Biasanya, Anda menggunakan satu hub untuk satu tujuan, misalnya, hub obrolan, atau hub pemberitahuan. Saat koneksi klien dibuat, koneksi terhubung ke hub, dan selama masa pakainya, koneksi tersebut milik hub tersebut. Aplikasi yang berbeda dapat berbagi satu Web PubSub dengan menggunakan nama hub yang berbeda.

Kelompok

Grup adalah subset koneksi ke hub. Anda dapat menambahkan koneksi klien ke grup, atau menghapus koneksi klien dari grup, kapan saja Anda mau. Misalnya, ketika klien bergabung dengan ruang obrolan, atau ketika klien meninggalkan ruang obrolan, ruang obrolan ini dapat dianggap sebagai grup. Klien dapat bergabung dengan beberapa grup, dan grup dapat berisi beberapa klien.

Pengguna

Koneksi ke Web PubSub bisa menjadi milik satu pengguna. Pengguna mungkin memiliki beberapa koneksi, misalnya saat satu pengguna terhubung di beberapa perangkat atau beberapa tab browser.

Masa Pakai Klien

Masing-masing klien Web PubSub aman untuk di-cache dan digunakan sebagai singleton selama masa pakai aplikasi. Panggilan balik peristiwa terdaftar memiliki masa pakai yang sama dengan klien. Ini berarti Anda dapat menambahkan atau menghapus panggilan balik kapan saja dan status pendaftaran tidak akan berubah setelah koneksi ulang atau klien dihentikan.

Bundel JavaScript

Untuk menggunakan pustaka klien ini di browser, pertama, Anda perlu menggunakan bunder. Untuk detail tentang cara melakukan ini, silakan lihat dokumentasi bundling kami.

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.

  • Pelacakan Langsung

    Gunakan alat Live Trace dari portal Web PubSub untuk melihat lalu lintas langsung.

Sumber daya tambahan

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

  • Last updated on