Bagikan melalui

Pustaka klien Azure Service Bus untuk JavaScript - versi 7.9.5

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

Gunakan 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 utama:

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

Memulai

Menginstal paket

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

npm install @azure/service-bus

Lingkungan yang didukung saat ini

Prasyarat

Mengonfigurasi TypeScript

Pengguna TypeScript harus menginstal definisi jenis Node:

npm install @types/node

Anda juga perlu mengaktifkan compilerOptions.allowSyntheticDefaultImports di tsconfig.json Anda. Perhatikan bahwa jika Anda telah mengaktifkan compilerOptions.esModuleInterop, allowSyntheticDefaultImports diaktifkan secara default. Lihat buku pegangan opsi pengkompilasi 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 membutuhkan 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 berikut ini ke dalam 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 React Native

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

Mengautentikasi klien

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

Menggunakan string koneksi

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

const { ServiceBusClient } = require("@azure/service-bus");

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

Informasi selengkapnya tentang konstruktor ini tersedia dalam 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.

const { ServiceBusClient } = require("@azure/service-bus");
const { DefaultAzureCredential } = require("@azure/identity");

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 yang berikut untuk mendapatkan token yang sesuai:

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

Informasi selengkapnya tentang konstruktor ini tersedia dalam dokumentasi API

Konsep utama

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

  • Antrean: Memungkinkan pengiriman dan penerimaan pesan. Sering digunakan untuk komunikasi titik-ke-titik.
  • Topik: Dibandingkan dengan Antrean, Topik lebih cocok untuk menerbitkan/berlangganan skenario. Topik dapat dikirim ke, tetapi memerlukan langganan, yang mungkin 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 tersebut. 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.

Contoh

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

Mengirim pesan

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

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

Terima pesan

Setelah membuat instans ServiceBusClient kelas, Anda bisa mendapatkan ServiceBusReceiver menggunakan metode createReceiver .

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

Ada dua receiveModeyang tersedia.

  • "peekLock" - Dalam mode peekLock, penerima memiliki kunci pada pesan selama durasi yang ditentukan pada antrean.
  • "receiveAndDelete" - Dalam mode receiveAndDelete, pesan dihapus dari Azure Service Bus 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 dengan salah satu dari 3 cara untuk menerima pesan:

Mendapatkan array pesan

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

const myMessages = await receiver.receiveMessages(10);

Berlangganan menggunakan handler pesan

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

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

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

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

Menyelesaikan pesan

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

Untuk mempelajari lebih lanjut, silakan baca Penetapan Pesan yang Diterima

Antrean Dead-letter

Antrean surat mati adalah sub-antrean. Setiap antrean atau langganan memiliki antrean surat mati sendiri. Antrean dead letter menyimpan pesan yang telah secara eksplisit dihentikan hurufnya (melalui 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:

// 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 surat mati lebih menyeluruh:

Mengirim pesan menggunakan Sesi

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

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

Saat mengirim pesan, atur sessionId properti dalam pesan untuk memastikan pesan Anda mendarat di sesi yang tepat.

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

Anda dapat membaca selengkapnya tentang cara kerja sesi di sini.

Menerima pesan dari Sesi

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

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

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

Ada dua cara untuk memilih sesi mana yang akan dibuka:

  1. sessionIdTentukan , yang mengunci sesi bernama.

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

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

    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 pilih antara 3 cara untuk menerima pesan:

Anda dapat membaca selengkapnya tentang cara kerja sesi di sini.

Mengelola sumber daya namespace bus layanan

ServiceBusAdministrationClient memungkinkan Anda mengelola namespace layanan 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 ServiceBusClientdengan .

Catatan: Azure Service Bus belum mendukung pengaturan aturan CORS untuk namespace layanan, sehingga ServiceBusAdministrationClient tidak akan berfungsi di browser tanpa menonaktifkan keamanan web. Untuk informasi selengkapnya, lihat di sini.

// 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);

await serviceBusAdministrationClient.deleteQueue(queueName);

Pemecahan Masalah

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

Dependensi AMQP

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

Pembuatan Log

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

  • Mendapatkan log debug dari Service Bus SDK
export DEBUG=azure*
  • Mendapatkan log debug dari Service Bus SDK dan pustaka tingkat protokol.
export DEBUG=azure*,rhea*
  • Jika Anda tidak tertarik untuk melihat transformasi pesan (yang mengonsumsi banyak ruang konsol/disk) maka Anda dapat mengatur DEBUG variabel lingkungan sebagai berikut:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Jika Anda hanya tertarik dengan 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 lingkungan seperti yang DEBUG 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 out.log yang sama 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 out.logyang sama . 
      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 Bus Layanan, Topik, dan Langganan.

Berkontribusi

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

Tayangan

  • Last updated on