Bagikan melalui

Pustaka klien Web PubSub untuk JavaScript

  • Artikel

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

Overflow

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

Pustaka ini dihosting di NPM.

Memulai

Lingkungan yang didukung saat ini

Prasyarat

1. pasang 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 di-genegrasi di server aplikasi Anda. Lihat detail di bawah )

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
let 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, connected peristiwa tersebut dipicu.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Ketika klien terputus dan gagal memulihkan koneksi, disconnected peristiwa 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 dipanggil client.stop() , atau autoReconnect dinonaktifkan atau batas tertentu untuk mencoba menyambungkan kembali telah tercapai. Jika Anda ingin menghidupkan 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 @azure/web-pubsubserver .

1. Server aplikasi

Cuplikan kode di bawah ini adalah contoh server aplikasi yang mengekspos /negotiate jalur 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) => {
  let 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 () => {
    let 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, jika 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 autoRejoinGroup opsi yang diaktifkan.

Namun, Anda harus menyadari autoRejoinGroupketerbatasannya.

  • Klien hanya dapat bergabung kembali dengan grup yang awalnya digabungkan dengan kode klien bukan 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 muncul. Anda dapat terus mencoba kembali dengan meneruskan yang sama ackId 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 subprotokul

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

Koneksi

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. Masing-masing WebPubSubClient menciptakan koneksi eksklusifnya sendiri.

Pemulihan

Jika klien yang menggunakan protokol andal terputus, WebSocket baru mencoba membuat menggunakan ID koneksi dari 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 1008 kesalahan WebSocket atau upaya pemulihan berlangsung lebih dari 30 detik, pemulihan gagal.

Sambungkan kembali

Koneksi ulang terjadi ketika koneksi klien terputus dan gagal dipulihkan. 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 serangkaian koneksi klien. Biasanya, Anda menggunakan satu hub untuk satu tujuan, misalnya, hub obrolan, atau hub pemberitahuan. Ketika koneksi klien dibuat, koneksi tersebut terhubung ke hub, dan selama masa pakainya, menjadi milik hub tersebut. Aplikasi yang berbeda dapat berbagi satu Web PubSub dengan menggunakan nama hub yang berbeda.

Grup

Grup adalah subset koneksi ke hub. Anda dapat menambahkan koneksi klien ke grup atau menghapus koneksi klien dari grup kapan saja Anda inginkan. Misalnya, saat klien bergabung dengan ruang obrolan atau saat klien keluar dari ruang obrolan, ruang obrolan semacam itu bisa menjadi grup. Klien dapat bergabung dengan beberapa grup, dan grup dapat berisi beberapa klien.

Pengguna

Koneksi ke Web PubSub dapat 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-tama, 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.

Sumber Daya Tambahan:

Berkontribusi

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