Bagikan melalui

JavaScript SDK untuk Azure Web PubSub

  • Artikel

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.

Ada dua pustaka yang ditawarkan untuk JavaScript: pustaka klien layanan dan middleware ekspres. Bagian berikut berisi informasi selengkapnya tentang pustaka ini.

Pustaka klien layanan Azure Web PubSub untuk JavaScript

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

The overflow diagram shows the overflow of using the service client library.

  • Mengirim pesan ke hub dan grup.
  • Mengirim pesan ke pengguna dan koneksi tertentu.
  • Mengatur pengguna dan sambungan ke dalam grup.
  • Menutup koneksi
  • Memberikan,mencabut, dan memeriksa izin untuk koneksi yang sudah ada

Kode sumber | Paket (NPM) | dokumentasi referensi API | Dokumentasi produk | Sampel

Memulai

Lingkungan yang didukung saat ini

Prasyarat

  • Langganan Azure.
  • Instans 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 ID Microsoft Entra

  1. Pasang dependensi @azure/identity
npm install @azure/identity
  1. Perbarui kode sumber untuk menggunakan DefaultAzureCredential:
const {
  WebPubSubServiceClient,
  AzureKeyCredential,
} = require("@azure/web-pubsub");

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

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" });

// 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 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: FullOperationResponse): void {
  console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient(
  "<ConnectionString>",
  "<hubName>"
);
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Pemecahan masalah klien layanan

Aktifkan Log

Anda dapat mengatur variabel lingkungan berikut untuk mendapatkan log debug saat menggunakan pustaka ini.

  • Mendapatkan log debug dari pustaka klien Azure Web PubSub
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.

Penghandel Azure Web PubSub CloudEvents untuk Ekspres

Ketika koneksi WebSocket terhubung, layanan Web PubSub mengubah siklus hidup koneksi dan pesan menjadi peristiwa dalam format CloudEvents. Pustaka ini menyediakan middleware ekspres untuk menangani peristiwa yang mewakili siklus hidup dan pesan koneksi WebSocket, seperti yang ditunjukkan pada diagram di bawah ini:

The overflow diagram shows the overflow of using the event handler middleware.

Kode sumber | Paket (NPM) | dokumentasi referensi API | Dokumentasi produk | Sampel

Memulai

Lingkungan yang didukung saat ini

Prasyarat

  • Langganan Azure.
  • Titik akhir Azure Web PubSub yang ada.

1. pasang paket @azure/web-pubsub-express

npm install @azure/web-pubsub-express

2. Membuat WebPubSubEventHandler

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Contoh ekspres

Menangani permintaan connect dan menetapkan <userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>",
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"],
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Hanya mengizinkan titik akhir yang ditentukan

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com",
  ],
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Mengatur jalur penangan peristiwa kustom

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "/customPath1",
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Mengatur dan membaca status koneksi

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  },
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(
    `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`
  )
);

Pemecahan Masalah

Aktifkan Log

Anda dapat mengatur variabel lingkungan berikut untuk mendapatkan log debug saat menggunakan pustaka ini.

  • Mendapatkan log debug dari pustaka klien Azure Web PubSub
export AZURE_LOG_LEVEL=verbose

Untuk instruksi lebih rinci tentang cara mengaktifkan log, lihat dokumen paket @azure/pencatat.

Jejak Hidup

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

Langkah berikutnya

Gunakan sumber daya ini untuk mulai membangun aplikasi Anda sendiri:

Tutorial: Menerbitkan dan berlangganan pesan di Azure Web PubSub

Tutorial: Membuat ruang obrolan sederhana dengan Azure Web PubSub

Tutorial: Menggunakan subprotokola yang didukung layanan untuk streaming klien

Tutorial: Bangun obrolan tanpa server dengan Azure Functions dan Web PubSub

Tutorial: Mengonfigurasi pendengar peristiwa

Bermain dengan demo langsung

Jelajahi sampel Azure Web PubSub lainnya