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

overflowoverflowluapan

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 dihasilkan 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".

import { WebPubSubClient } from "@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();

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.

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");

// 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}`);
});

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

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

4. Mengirim pesan ke grup

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";
await client.joinGroup(groupName);

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

5. Memanggil peristiwa hulu (pratinjau)

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const result = await client.invokeEvent("processOrder", { orderId: 1 }, "json");
console.log(`Invocation result: ${JSON.stringify(result.data)}`);

invokeEvent mengirim invoke permintaan ke layanan, menunggu korelasi invokeResponse, dan mengembalikan payload. Anda dapat membatalkan pemanggilan dengan meneruskan { abortSignal }. Pemanggilan streaming dan layanan yang dimulai belum didukung.

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.

import express from "express";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
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.

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    const negotiate = await fetch("/negotiate");
    const { url } = await negotiate.json();
    return 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.
import { WebPubSubClient } from "@azure/web-pubsub-client";

// 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.

import { WebPubSubClient, SendMessageError } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";

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.

import { WebPubSubClient, WebPubSubJsonProtocol } from "@azure/web-pubsub-client";

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

import { WebPubSubClient, WebPubSubJsonReliableProtocol } from "@azure/web-pubsub-client";

// 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

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info.

export AZURE_LOG_LEVEL=verbose

Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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