Azure Service Bus client library untuk JavaScript - versi 7.10.0

Azure Service Bus adalah layanan perpesanan cloud yang sangat andal dari Microsoft.

Menggunakan pustaka @azure/service-bus klien di aplikasi Anda untuk

  • Mengirim pesan ke Antrean atau Topik Azure Service Bus
  • Menerima pesan dari Antrean atau Langganan Azure Service Bus
  • Buat/Dapatkan/Hapus/Perbarui/Daftar Antrean/Topik/Langganan/Aturan di namespace Azure Service Bus.

Sumber daya untuk @azure/service-bus versi 7:

Tautan kunci:

CATATAN: Jika Anda menggunakan versi 1.1.10 atau lebih rendah dan ingin bermigrasi ke versi terbaru dari paket ini, silakan lihat panduan migrasi kami untuk beralih dari Bus Layanan V1 ke Bus Layanan V7

Memulai Langkah Pertama

Pasang paketnya

Instal versi terbaru untuk pustaka klien Azure Service Bus menggunakan npm.

npm install @azure/service-bus

Lingkungan yang didukung saat ini

Prerequisites

Mengonfigurasi TypeScript

Pengguna TypeScript harus menginstal definisi jenis Node:

npm install @types/node

Anda juga perlu mengaktifkan compilerOptions.allowSyntheticDefaultImports di tsconfig.jsonAnda. Perhatikan bahwa jika Anda telah mengaktifkan compilerOptions.esModuleInterop, allowSyntheticDefaultImports diaktifkan secara default. Lihat opsi kompilator TypeScript untuk informasi selengkapnya.

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.

Selain apa yang dijelaskan di sana, pustaka ini juga memerlukan polifill tambahan untuk modul bawaan inti NodeJS berikut agar berfungsi dengan baik di browser:

  • buffer
  • os
  • path
  • process

Bundling dengan Webpack

Jika Anda menggunakan Webpack v5, Anda dapat menginstal dependensi dev berikut

  • npm install --save-dev os-browserify path-browserify

lalu tambahkan hal berikut ke webpack.config.js Anda

 const path = require("path");
+const webpack = require("webpack");

 module.exports = {
   entry: "./src/index.ts",
@@ -12,8 +13,21 @@ module.exports = {
       },
     ],
   },
+  plugins: [
+    new webpack.ProvidePlugin({
+      process: "process/browser",
+    }),
+    new webpack.ProvidePlugin({
+      Buffer: ["buffer", "Buffer"],
+    }),
+  ],
   resolve: {
     extensions: [".ts", ".js"],
+    fallback: {
+      buffer: require.resolve("buffer/"),
+      os: require.resolve("os-browserify"),
+      path: require.resolve("path-browserify"),
+    },
   },

Bundling dengan Rollup

Jika Anda menggunakan bunder Rollup, instal dependensi dev berikut

  • npm install --save-dev @rollup/plugin-commonjs @rollup/plugin-inject @rollup/plugin-node-resolve

Kemudian sertakan yang berikut ini di rollup.config.js Anda

+import nodeResolve from "@rollup/plugin-node-resolve";
+import cjs from "@rollup/plugin-commonjs";
+import shim from "rollup-plugin-shim";
+import inject from "@rollup/plugin-inject";

export default {
  // other configs
  plugins: [
+    shim({
+      fs: `export default {}`,
+      net: `export default {}`,
+      tls: `export default {}`,
+      path: `export default {}`,
+      dns: `export function resolve() { }`,
+    }),
+    nodeResolve({
+      mainFields: ["module", "browser"],
+      preferBuiltins: false,
+    }),
+    cjs(),
+    inject({
+      modules: {
+        Buffer: ["buffer", "Buffer"],
+        process: "process",
+      },
+      exclude: ["./**/package.json"],
+    }),
  ]
};

Silakan lihat dokumentasi bunder favorit Anda untuk informasi lebih lanjut tentang menggunakan polifill.

Dukungan Asli React

Mirip dengan browser, React Native tidak mendukung beberapa API JavaScript yang digunakan oleh pustaka SDK ini sehingga Anda perlu menyediakan polyfill untuk mereka. Silakan lihat sampel Messaging React Native dengan Expo untuk detail selengkapnya.

Mengautentikasi klien

Interaksi dengan Bus Layanan dimulai dengan instans kelas ServiceBusClient . Anda dapat mengautentikasi ke Bus Layanan menggunakan string koneksi atau menggunakan kredensial Azure Active Directory.

Menggunakan string koneksi

Metode ini mengambil string koneksi ke instans Bus Layanan Anda. Anda bisa mendapatkan string koneksi dari portal Microsoft Azure.

import { ServiceBusClient } from "@azure/service-bus";

const serviceBusClient = new ServiceBusClient("<connectionString>");

Informasi selengkapnya tentang konstruktor ini tersedia di dokumentasi API.

Menggunakan Kredensial Azure Active Directory

Autentikasi dengan Azure Active Directory menggunakan pustaka Azure Identity.

Contoh di bawah ini menggunakan DefaultAzureCredential, salah satu dari banyak penyedia kredensial yang tersedia dari @azure/identity pustaka.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

CATATAN: Jika Anda menggunakan implementasi TokenCredential antarmuka Anda sendiri terhadap AAD, atur "cakupan" untuk service-bus ke berikut ini untuk mendapatkan token yang sesuai:

["https://servicebus.azure.net//user_impersonation"];

Informasi selengkapnya tentang konstruktor ini tersedia di dokumentasi API

Konsep Utama

Setelah Anda menginisialisasi ServiceBusClient, Anda dapat berinteraksi dengan sumber daya ini dalam Namespace Bus Layanan:

  • Antrean: Memungkinkan pengiriman dan penerimaan pesan. Sering digunakan untuk komunikasi point-to-point.
  • Topik: Dibandingkan dengan Antrean, Topik lebih cocok untuk memublikasikan skenario berlangganan. Topik dapat dikirim ke, tetapi memerlukan langganan, yang dapat ada beberapa secara paralel, untuk dikonsumsi.
  • Langganan: Mekanisme untuk mengonsumsi dari Topik. Setiap langganan bersifat independen, dan menerima salinan setiap pesan yang dikirim ke topik. Aturan dan Filter dapat digunakan untuk menyesuaikan pesan mana yang diterima oleh langganan tertentu.

Untuk informasi selengkapnya tentang sumber daya ini, lihat Apa itu Azure Service Bus?.

Untuk berinteraksi dengan sumber daya ini, seseorang harus terbiasa dengan konsep SDK berikut:

Harap dicatat bahwa Antrean, Topik, dan Langganan harus dibuat sebelum menggunakan pustaka ini.

Examples

Bagian berikut menyediakan cuplikan kode yang mencakup beberapa tugas umum menggunakan Azure Service Bus

Mengirim pesan

Setelah Anda membuat instance kelas ServiceBusClient , Anda bisa mendapatkan ServiceBusSender metode createSender yang dapat Anda gunakan untuk mengirim pesan.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const sender = serviceBusClient.createSender("my-queue");

const messages = [
  { body: "Albert Einstein" },
  { body: "Werner Heisenberg" },
  { body: "Marie Curie" },
  { body: "Steven Hawking" },
  { body: "Isaac Newton" },
  { body: "Niels Bohr" },
  { body: "Michael Faraday" },
  { body: "Galileo Galilei" },
  { body: "Johannes Kepler" },
  { body: "Nikolaus Kopernikus" },
];

// sending a single message
await sender.sendMessages(messages[0]);

// sending multiple messages in a single call
// this will fail if the messages cannot fit in a batch
await sender.sendMessages(messages);

// Sends multiple messages using one or more ServiceBusMessageBatch objects as required
let batch = await sender.createMessageBatch();

for (let i = 0; i < messages.length; i++) {
  const message = messages[i];
  if (!batch.tryAddMessage(message)) {
    // Send the current batch as it is full and create a new one
    await sender.sendMessages(batch);
    batch = await sender.createMessageBatch();

    if (!batch.tryAddMessage(messages[i])) {
      throw new Error("Message too big to fit in a batch");
    }
  }
}
// Send the batch
await sender.sendMessages(batch);

Menerima pesan

Setelah Anda membuat instance kelas ServiceBusClient , Anda bisa mendapatkan metode ServiceBusReceivermenggunakan createReceiver .

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

Ada dua receiveModes yang tersedia.

  • "peekLock" - Dalam mode peekLock, penerima memiliki kunci pada pesan selama durasi yang ditentukan pada antrean.
  • "receiveAndDelete" - Dalam mode receiveAndDelete, pesan dihapus dari Bus Layanan saat diterima.

Jika receiveMode tidak disediakan dalam opsi, itu default ke mode "peekLock". Anda juga dapat menyelesaikan pesan yang diterima dalam mode "peekLock".

Anda dapat menggunakan penerima ini dalam salah satu dari 3 cara untuk menerima pesan:

Mendapatkan array pesan

Gunakan fungsi receiveMessages yang mengembalikan janji yang diselesaikan ke array pesan.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

const myMessages = await receiver.receiveMessages(10);

Berlangganan menggunakan penangan pesan

Gunakan metode berlangganan untuk menyiapkan penanganan pesan dan menjalankannya selama yang Anda butuhkan.

Setelah selesai, hubungi receiver.close() untuk berhenti menerima pesan lagi.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

const myMessageHandler = async (message) => {
  // your code here
  console.log(`message.body: ${message.body}`);
};
const myErrorHandler = async (args) => {
  console.log(
    `Error occurred with ${args.entityPath} within ${args.fullyQualifiedNamespace}: `,
    args.error,
  );
};
receiver.subscribe({
  processMessage: myMessageHandler,
  processError: myErrorHandler,
});

Menggunakan iterator asinkron

Gunakan getMessageIterator untuk mendapatkan iterator asinkron melalui pesan

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const receiver = serviceBusClient.createReceiver("my-queue");

for await (const message of receiver.getMessageIterator()) {
  // your code here
}

Menyelesaikan pesan

Setelah menerima pesan, Anda dapat menelepon completeMessage(), abandonMessage(), deferMessage() atau deadLetterMessage() pada penerima berdasarkan cara Anda ingin menyelesaikan pesan.

Untuk mempelajari lebih lanjut, silakan baca Menyelesaikan Pesan yang Diterima

Antrean Surat Mati

Antrean huruf mati adalah sub-antrean. Setiap antrean atau langganan memiliki antrean surat matinya sendiri. Antrean surat mati menyimpan pesan yang telah di-mati secara eksplisit (via receiver.deadLetterMessage()), atau pesan yang telah melebihi jumlah pengiriman maksimumnya.

Membuat penerima untuk sub-antrean surat mati mirip dengan membuat penerima untuk langganan atau antrean:

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

// To receive from a queue's dead letter sub-queue
const deadLetterReceiverForQueue = serviceBusClient.createReceiver("queue", {
  subQueueType: "deadLetter",
});

// To receive from a subscription's dead letter sub-queue
const deadLetterReceiverForSubscription = serviceBusClient.createReceiver("topic", "subscription", {
  subQueueType: "deadLetter",
});

// Dead letter receivers work like any other receiver connected to a queue
// ex:
const messages = await deadLetterReceiverForQueue.receiveMessages(5);

for (const message of messages) {
  console.log(`Dead lettered message: ${message.body}`);
}

Sampel lengkap yang menunjukkan antrean huruf mati secara lebih menyeluruh:

Mengirim pesan menggunakan Sesi

Menggunakan sesi mengharuskan Anda membuat Antrean atau Langganan yang diaktifkan sesi. Anda dapat membaca lebih lanjut tentang cara mengonfigurasi fitur ini di portal di sini.

Untuk mengirim pesan ke sesi, gunakan untuk ServiceBusClient membuat pengirim menggunakan createSender.

Saat mengirim pesan, atur sessionId properti dalam pesan untuk memastikan pesan Anda masuk ke sesi yang benar.

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

const sender = serviceBusClient.createSender("my-session-queue");
await sender.sendMessages({
  body: "my-message-body",
  sessionId: "my-session",
});

Anda dapat membaca lebih lanjut tentang cara kerja sesi di sini.

Menerima pesan dari Sesi

Menggunakan sesi mengharuskan Anda membuat Antrean atau Langganan yang diaktifkan sesi. Anda dapat membaca lebih lanjut tentang cara mengonfigurasi fitur ini di portal di sini.

Tidak seperti Antrean atau Langganan yang tidak diaktifkan sesi, hanya satu penerima yang dapat membaca dari sesi kapan saja. Ini diberlakukan dengan mengunci sesi, yang ditangani oleh Bus Layanan. Secara konseptual, ini mirip dengan cara kerja penguncian pesan saat menggunakan peekLock mode - ketika pesan (atau sesi) dikunci, penerima Anda memiliki akses eksklusif ke sana.

Untuk membuka dan mengunci sesi, gunakan instance of ServiceBusClient untuk membuat SessionReceiver.

Ada dua cara untuk memilih sesi mana yang akan dibuka:

  1. Tentukan sessionId, yang mengunci sesi bernama.

    const receiver = await serviceBusClient.acceptSession("my-session-queue", "my-session");

  2. Jangan tentukan id sesi. Dalam hal ini Bus Layanan akan menemukan sesi berikutnya yang tersedia yang belum terkunci.

    const receiver = await serviceBusClient.acceptNextSession("my-session-queue");

    Anda dapat menemukan nama sesi melalui sessionId properti di .SessionReceiver Jika receiveMode tidak disediakan dalam opsi, itu default ke mode "peekLock". Anda juga dapat menyelesaikan pesan yang diterima dalam mode "peekLock".

Setelah penerima dibuat, Anda dapat menggunakan pilihan di antara 3 cara untuk menerima pesan:

Anda dapat membaca lebih lanjut tentang cara kerja sesi di sini.

Daftar sesi pesan

Untuk menemukan sesi mana yang memiliki pesan aktif atau status sesi dalam antrian atau langganan, gunakan listMessageSessions():

import { DefaultAzureCredential } from "@azure/identity";
import { ServiceBusClient } from "@azure/service-bus";

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

// List all sessions with active messages or session state in a queue
for await (const sessionId of serviceBusClient.listMessageSessions("my-session-queue")) {
  console.log("Session ID:", sessionId);
}

// List sessions in a subscription
for await (const sessionId of serviceBusClient.listMessageSessions("my-topic", "my-subscription")) {
  console.log("Session ID:", sessionId);
}

// List only sessions whose stored session state was set or updated in the last seven days
const sessionStateUpdatedAfter = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
for await (const sessionId of serviceBusClient.listMessageSessions("my-session-queue", {
  sessionStateUpdatedAfter,
})) {
  console.log("Recently updated session ID:", sessionId);
}

Mengelola sumber daya namespace bus layanan

ServiceBusAdministrationClient memungkinkan Anda mengelola namespace dengan operasi CRUD pada entitas (antrean, topik, dan langganan) dan pada aturan langganan.

  • Mendukung autentikasi dengan string koneksi bus layanan serta dengan kredensial AAD dari @azure/identity yang mirip dengan .ServiceBusClient

Catatan: Bus Layanan belum mendukung pengaturan aturan CORS untuk namespace, sehingga ServiceBusAdministrationClient tidak akan berfungsi di browser tanpa menonaktifkan keamanan web. Untuk info lebih lanjut, lihat di sini.

import { ServiceBusAdministrationClient } from "@azure/service-bus";

const queueName = "my-session-queue";

// Get the connection string from the portal
// OR
// use the token credential overload, provide the host name of your Service Bus instance and the AAD credentials from the @azure/identity library
const serviceBusAdministrationClient = new ServiceBusAdministrationClient("<connectionString>");

// Similarly, you can create topics and subscriptions as well.
const createQueueResponse = await serviceBusAdministrationClient.createQueue(queueName);
console.log("Created queue with name - ", createQueueResponse.name);

const queueRuntimeProperties =
  await serviceBusAdministrationClient.getQueueRuntimeProperties(queueName);
console.log(`Number of messages in the queue = ${queueRuntimeProperties.totalMessageCount}`);

// Topic runtime properties additionally report the total number of SQL and correlation filters
// across all of the topic's subscriptions. These counts are served by the 2024-05 service API
// version and later; on an older version they are `undefined`.
const topicName = "my-topic";
const subscriptionName = "my-subscription";
await serviceBusAdministrationClient.createTopic(topicName);
// A new subscription carries a default rule with a SQL TrueFilter. Adding a correlation rule
// gives the topic one of each, so the counts below aggregate across the subscription's rules.
await serviceBusAdministrationClient.createSubscription(topicName, subscriptionName);
await serviceBusAdministrationClient.createRule(
  topicName,
  subscriptionName,
  "my-correlation-rule",
  { correlationId: "my-correlation-id" },
);
const topicRuntimeProperties =
  await serviceBusAdministrationClient.getTopicRuntimeProperties(topicName);
console.log(`SQL filter count = ${topicRuntimeProperties.sqlFilterCount}`);
console.log(`Correlation filter count = ${topicRuntimeProperties.correlationFilterCount}`);

await serviceBusAdministrationClient.deleteTopic(topicName);
await serviceBusAdministrationClient.deleteQueue(queueName);

Troubleshooting

Berikut adalah beberapa langkah awal untuk mulai mendiagnosis masalah. Untuk informasi lebih lanjut, silakan lihat Panduan Pemecahan Masalah Bus Layanan.

Dependensi AMQP

Pustaka Bus Layanan bergantung pada pustaka rhea-promise untuk mengelola koneksi, mengirim dan menerima pesan melalui protokol AMQP .

Logging

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

  • Mendapatkan log debug dari Bus Layanan SDK
export DEBUG=azure*
  • Mendapatkan log debug dari Bus Layanan SDK dan pustaka tingkat protokol.
export DEBUG=azure*,rhea*
  • Jika Anda tidak tertarik untuk melihat transformasi pesan (yang menghabiskan banyak ruang konsol/disk) maka Anda dapat mengatur variabel DEBUG lingkungan sebagai berikut:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Jika Anda hanya tertarik pada kesalahan, maka Anda dapat mengatur DEBUG variabel lingkungan sebagai berikut:
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Pengelogan ke file

  1. Atur variabel DEBUG lingkungan seperti yang ditunjukkan di atas
  2. Jalankan skrip pengujian Anda sebagai berikut:
  • Pernyataan pengelogan dari skrip pengujian Anda masuk ke out.log dan pernyataan pengelogan dari sdk buka debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Pernyataan pengelogan dari skrip pengujian Anda dan sdk masuk ke file yang sama out.log dengan mengalihkan stderr ke stdout (&1), lalu alihkan stdout ke file: 
    node your-test-script.js >out.log 2>&1
  • Pernyataan pengelogan dari skrip pengujian Anda dan sdk masuk ke file yang sama out.log. 
      node your-test-script.js &> out.log

Langkah berikutnya

Silakan lihat direktori sampel untuk contoh terperinci tentang cara menggunakan pustaka ini untuk mengirim dan menerima pesan ke/dari Antrean, Topik, dan Langganan Bus Layanan.

Contributing

Jika Anda ingin berkontribusi ke library ini, silakan baca panduan contributor untuk mempelajari lebih lanjut cara membuat dan menguji kode.

  • Terakhir diperbarui pada