Pustaka klien layanan Azure Web PubSub untuk JavaScript - versi 1.2.0

Layanan Azure Web PubSub adalah layanan terkelola Azure yang membantu pengembang dengan mudah membangun aplikasi web dengan fitur real-time dan pola publikasi-langganan. Skenario apa pun yang memerlukan pesan terbitkan-berlangganan real time antara server dan klien atau di antara klien dapat menggunakan layanan Azure Web PubSub. Fitur real-time tradisional yang sering memerlukan polling dari server atau mengirimkan permintaan HTTP juga dapat menggunakan layanan Azure Web PubSub.

Anda dapat menggunakan pustaka ini di sisi server aplikasi untuk mengelola koneksi klien WebSocket, seperti yang ditunjukkan pada diagram di bawah ini:

meluap .

Mengirim pesan ke hub dan grup.
Mengirim pesan ke pengguna dan koneksi tertentu.
Atur pengguna dan koneksi ke dalam grup.
Tutup koneksi
Memberikan, mencabut, dan memeriksa izin untuk koneksi yang sudah ada

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

Kode | sumberPaket (NPM) | Dokumentasi | referensi APIDokumentasi | produkSampel

Persiapan

Lingkungan yang saat ini didukung

Versi LTS dari Node.js

Prasyarat

Sebuah langganan Azure.
Instans layanan Azure Web PubSub yang sudah ada.

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

npm install @azure/web-pubsub

2. Membuat dan mengautentikasi WebPubSubServiceClient

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

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

Anda juga dapat mengautentikasi menggunakan WebPubSubServiceClient titik akhir dan AzureKeyCredential:

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

const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Atau autentikasi menggunakan WebPubSubServiceClientAzure Active Directory

Menginstal @azure/identity dependensi

npm install @azure/identity

Perbarui kode sumber untuk menggunakan DefaultAzureCredential:

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

const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Konsep utama

Sambungan

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

Pusat

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 layanan Azure 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.

Pesan

Ketika klien terhubung, klien dapat mengirim pesan ke aplikasi upstream, atau menerima pesan dari aplikasi upstram, melalui koneksi WebSocket.

Contoh

Mendapatkan token akses bagi klien untuk memulai koneksi WebSocket

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();

// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });

// Or get the access token that the client will join group GroupA when it connects using the access token
token = await serviceClient.getClientAccessToken({ userId: "user1", groups: ["GroupA"] });

Menyiarkan pesan ke semua koneksi di hub

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);

Mengirim pesan ke semua koneksi di hub dengan sintaks filter OData

Detail tentang filter sintaks, silakan lihat sintaks filter OData untuk Azure Web PubSub.

import { WebPubSubServiceClient, odata } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Send a JSON message to anonymous connections
await serviceClient.sendToAll({ message: "Hello world!" }, { filter: "userId eq null" });

// Send a text message to connections in groupA but not in groupB
const groupA = "groupA";
const groupB = "groupB";
await serviceClient.sendToAll("Hello world!", {
  contentType: "text/plain",
  // use plain text "'groupA' in groups and not('groupB' in groups)"
  // or use the odata helper method
  filter: odata`${groupA} in groups and not(${groupB} in groups)`,
});

Mengirim pesan ke semua koneksi dalam grup

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

const groupClient = serviceClient.group("<groupName>");

// Add user to the group
await groupClient.addUser("user1");

// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);

Mengirim pesan ke semua koneksi untuk pengguna

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);

Periksa apakah grup memiliki koneksi

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

const groupClient = serviceClient.group("<groupName>");

// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });

// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");

Mengakses respons HTTP mentah untuk operasi

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<hubName>",
);

function onResponse(rawResponse) {
  console.log(rawResponse);
}

await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

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

Pelacakan Langsung

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

Langkah berikutnya

Silakan lihat sampel direktori untuk contoh terperinci tentang cara menggunakan pustaka ini.

Berkontribusi

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

Microsoft Azure SDK untuk Javascript

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-05-17