Pustaka klien layanan Azure Web PubSub untuk JavaScript - versi 1.1.1
Layanan Azure Web PubSub adalah layanan terkelola Azure yang bertujuan untuk memudahkan pengembang membuat aplikasi web dengan fitur real-time dan pola terbitkan-berlangganan. Skenario apa pun yang memerlukan olahpesan 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 pengiriman permintaan HTTP juga dapat menggunakan layanan Azure Web PubSub.
Anda dapat menggunakan pustaka ini di sisi server aplikasi Anda untuk mengelola koneksi klien WebSocket, seperti yang ditunjukkan pada diagram di bawah ini:
- Mengirim pesan ke hub dan grup.
- Mengirim pesan ke pengguna dan koneksi tertentu.
- Mengatur pengguna dan sambungan ke dalam grup.
- Tutup koneksi
- Memberikan,mencabut, dan memeriksa izin untuk koneksi yang sudah ada
Rincian tentang ketentuan yang digunakan dijelaskan di bagian Konsep kunci.
Kode sumber | Paket (NPM) | dokumentasi referensi API | Dokumentasi produk | Sampel
Memulai
Lingkungan yang didukung saat ini
Prasyarat
- Langganan Azure.
- Contoh layanan Azure Web PubSub yang sudah ada.
1. pasang paket @azure/web-pubsub
npm install @azure/web-pubsub
2. Membuat dan mengautentikasi WebPubSubServiceClient
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
Anda juga dapat mengautentikasi WebPubSubServiceClient
penggunaan titik akhir AzureKeyCredential
dan:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");
Atau autentikasi WebPubSubServiceClient
menggunakan Azure Active Directory
- Pasang dependensi
@azure/identity
npm install @azure/identity
- Perbarui kode sumber untuk menggunakan
DefaultAzureCredential
:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");
const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");
Konsep utama
Koneksi
Koneksi, juga dikenal sebagai klien atau koneksi klien, mewakili koneksi WebSocket individu yang terhubung ke layanan Web PubSub. Jika berhasil terhubung, ID koneksi unik ditetapkan ke koneksi ini oleh layanan Web PubSub.
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 layanan Azure 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.
Pesan
Saat terhubung, klien dapat mengirim pesan ke aplikasi upstream atau menerima pesan dari aplikasi upstream melalui koneksi WebSocket.
Contoh
Dapatkan token akses bagi klien untuk memulai koneksi WebSocket
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<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" ] });
// return the token to the WebSocket client
Menyiarkan pesan ke semua koneksi di hub
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<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
sintaksis silakan lihat sintaks filter OData untuk Azure Web PubSub.
const { WebPubSubServiceClient, odata } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<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
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<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
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<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
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const WebSocket = require("ws");
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<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
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
function onResponse(rawResponse) {
console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });
Pemecahan Masalah
Aktifkan log
Anda dapat mengatur variabel lingkungan berikut untuk mendapatkan log debug saat menggunakan pustaka ini.
- Mendapatkan log debug dari pustaka klien SignalR
export AZURE_LOG_LEVEL=verbose
Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.
Jejak Hidup
Gunakan Live Trace dari portal layanan Web PubSub untuk melihat lalu lintas langsung.
Langkah berikutnya
Silakan lihat direktori sampel 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.
Proyek terkait
Azure SDK for JavaScript
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk