Azure Service Bus client library for JavaScript - version 7.10.0

Azure Service Bus är en mycket tillförlitlig meddelandetjänst i molnet från Microsoft.

Använd klientbiblioteket @azure/service-bus i ditt program för att

  • Skicka meddelanden till en Azure Service Bus-kö eller ett ämne
  • Ta emot meddelanden från en Azure Service Bus-kö eller prenumeration
  • Skapa/Hämta/Ta bort/Uppdatera/Lista köer/Ämnen/Prenumerationer/Regler i ett Azure Service Bus-namnområde.

Resurser för @azure/service-bus version 7:

Nyckellänkar:

Om du använder version 1.1.10 eller tidigare och vill migrera till den senaste versionen av det här paketet kan du läsa vår migreringsguide för att flytta från Service Bus V1 till Service Bus V7

Komma igång

Installera paketet

Installera den senaste versionen för Azure Service Bus-klientbiblioteket med hjälp av npm.

npm install @azure/service-bus

Miljöer som stöds för närvarande

Prerequisites

Konfigurera TypeScript

TypeScript-användare måste ha definitioner av nodtyp installerade:

npm install @types/node

Du måste också aktivera compilerOptions.allowSyntheticDefaultImports i din tsconfig.json. Observera att om du har aktiverat compilerOptions.esModuleInteropär allowSyntheticDefaultImports aktiverat som standard. Mer information finns i TypeScripts handbok för kompilatoralternativ.

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

Förutom det som beskrivs där behöver biblioteket även ytterligare polyfiller för följande inbyggda NodeJS-kärnmoduler för att fungera korrekt i webbläsarna:

  • buffer
  • os
  • path
  • process

Paketera med webpack

Om du använder Webpack v5 kan du installera följande dev-beroenden

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

lägg sedan till följande i din webpack.config.js

 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"),
+    },
   },

Sammanslagning med sammanslagning

Om du använder Sammanslagningspaket installerar du följande dev-beroenden

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

Ta sedan med följande i din rollup.config.js

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

Mer information om hur du använder polyfiller finns i dokumentationen för ditt favoritpaket.

Stöd för React Native

I likhet med webbläsare stöder React Native inte vissa JavaScript-api som används av detta SDK-bibliotek, så du måste tillhandahålla polyfills för dem. Mer information finns i det interna exemplet Messaging React med Expo.

Autentisera klienten

Interaktionen med Service Bus börjar med en instans av ServiceBusClient klassen. Du kan autentisera till Service Bus med hjälp av en συμβολοσειρά σύνδεσης eller med hjälp av en Azure Active T

Använda en anslutningssträng

Den här metoden tar συμβολοσειρά σύνδεσ Du kan hämta anslutningssträngen från Azure-portalen.

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

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

Mer information om den här konstruktorn finns i API-dokumentationen.

Använda en Azure Active Directory-autentiseringsuppgift

Autentisering med Azure Active Directory använder Azure Identity-biblioteket.

I exemplet nedan används DefaultAzureCredential, en av många tillgängliga leverantörer av autentiseringsuppgifter från @azure/identity biblioteket.

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

OBSERVERA: Om du använder din egen implementering av TokenCredential gränssnittet mot AAD anger du "omfången" för service-bus till följande för att få lämplig token:

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

Mer information om den här konstruktorn finns i API-dokumentationen

Viktiga begrepp

När du har initierat en ServiceBusClientkan du interagera med dessa resurser i ett Service Bus-namnområde:

  • Köer: Gör det möjligt att skicka och ta emot meddelanden. Används ofta för punkt-till-punkt-kommunikation.
  • Ämnen: Till skillnad från köer passar ämnen bättre för att publicera/prenumerera scenarier. Ett ämne kan skickas till, men kräver en prenumeration, som det kan finnas flera av parallellt, att använda från.
  • Prenumerationer: Mekanismen för att använda från ett ämne. Varje prenumeration är oberoende och får en kopia av varje meddelande som skickas till ämnet. Regler och filter kan användas för att skräddarsy vilka meddelanden som tas emot av en specifik prenumeration.

Mer information om dessa resurser finns i Vad är Azure Service Bus?.

Om du vill interagera med dessa resurser bör du vara bekant med följande SDK-begrepp:

Observera att köer, ämnen och prenumerationer bör skapas innan du använder det här biblioteket.

Examples

Följande avsnitt innehåller kodfragment som beskriver några av de vanliga uppgifterna med hjälp av Azure Service Bus

Skicka meddelanden

När du har skapat en instans av en ServiceBusClient klass kan du få en ServiceBusSender med metoden createSender som du kan använda för att skicka meddelanden.

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

Ta emot meddelanden

När du har skapat en instans av en ServiceBusClient klass kan du få en ServiceBusReceiver med hjälp av createReceiver metoden .

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

Det finns två receiveModes tillgängliga.

  • "peekLock" – I peekLock-läge har mottagaren ett lås på meddelandet under den varaktighet som anges i kön.
  • "receiveAndDelete" – I receiveAndDelete-läge tas meddelanden bort från Service Bus när de tas emot.

Om receiveMode inte anges i alternativen används som standard "peekLock"-läget. Du kan också reglera de meddelanden som tas emot i "peekLock"-läge.

Du kan använda den här mottagaren på ett av 3 sätt för att ta emot meddelanden:

Hämta en matris med meddelanden

receiveMessages Använd funktionen som returnerar ett löfte som matchar en matris med meddelanden.

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

Prenumerera med hjälp av en meddelandehanterare

Använd subscribe metoden för att konfigurera meddelandehanterare och köra den så länge du behöver.

När du är klar ringer du receiver.close() för att sluta ta emot fler meddelanden.

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

Använda asynkron iterator

Använd getMessageIterator för att hämta en asynkron iterator över meddelanden

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
}

Lösa ett meddelande

När du har fått ett meddelande kan du ringa completeMessage(), abandonMessage(), deferMessage() eller deadLetterMessage() på mottagaren baserat på hur du vill lösa meddelandet.

Om du vill veta mer kan du läsa Reglera mottagna meddelanden

Döda bokstavs-köer

Kön för obeställbara meddelanden är en underkö. Varje kö eller prenumeration har en egen kö för obeställbara meddelanden. Köer för obeställbara meddelanden lagrar meddelanden som uttryckligen har tilldelats obeställbara bokstäver (via receiver.deadLetterMessage()) eller meddelanden som har överskridit det maximala antalet leveranser.

Att skapa en mottagare för en underkö med obeställbara meddelanden liknar att skapa en mottagare för en prenumeration eller kö:

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

Fullständiga exempel som visar köer för obeställbara meddelanden mer noggrant:

Skicka meddelanden med hjälp av sessioner

Om du använder sessioner måste du skapa en sessionsaktiverad kö eller prenumeration. Du kan läsa mer om hur du konfigurerar den här funktionen i portalen här.

Om du vill skicka meddelanden till en session använder du för ServiceBusClient att skapa en avsändare med hjälp av createSender.

När du skickar meddelandet anger du egenskapen sessionId i meddelandet för att säkerställa att meddelandet hamnar i rätt session.

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

Du kan läsa mer om hur sessionerna fungerar här.

Ta emot meddelanden från sessioner

Om du använder sessioner måste du skapa en sessionsaktiverad kö eller prenumeration. Du kan läsa mer om hur du konfigurerar den här funktionen i portalen här.

Till skillnad från icke-sessionsaktiverade köer eller prenumerationer kan endast en enda mottagare läsa från en session när som helst. Detta framtvingas genom att låsa en session, som hanteras av Service Bus. Konceptuellt liknar detta hur meddelandelåsning fungerar när du använder peekLock läge - när ett meddelande (eller session) är låst har din mottagare exklusiv tillgång till det.

Om du vill öppna och låsa en session använder du en instans av ServiceBusClient för att skapa en SessionReceiver.

Det finns två sätt att välja vilken session som ska öppnas:

  1. Ange en sessionId, som låser en namngiven session.

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

  2. Ange inte ett sessions-ID. I det här fallet hittar Service Bus nästa tillgängliga session som inte redan är låst.

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

    Du hittar namnet på sessionen via sessionId egenskapen på .SessionReceiver Om receiveMode inte anges i alternativen används som standard "peekLock"-läget. Du kan också reglera de meddelanden som tas emot i "peekLock"-läge.

När mottagaren är skapad kan du välja mellan 3 sätt att ta emot meddelanden:

Du kan läsa mer om hur sessionerna fungerar här.

Listmeddelandesessioner

För att upptäcka vilka sessioner som har aktiva meddelanden eller sessionstillstånd i en kö eller prenumeration, använd 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);
}

Hantera resurser i ett Service Bus-namnområde

ServiceBusAdministrationClient kan du hantera ett namnområde med CRUD-åtgärder för entiteterna (köer, ämnen och prenumerationer) och reglerna för en prenumeration.

  • Stöder autentisering med en Service Bus-συμβολοσειρά σύνδεσης samt med AAD-autentiseringsuppgifter från @azure/identity liknande ServiceBusClient.

Service Bus har inte stöd för att ställa in CORS-regler för namnrymder ännu, och fungerar därför ServiceBusAdministrationClient inte i webbläsaren utan att inaktivera webbsäkerhet. Mer information finns här.

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

Här är några inledande steg för att börja diagnostisera problem. Mer information finns i felsökningsguiden för Service Bus.

AMQP-beroenden

Service Bus-biblioteket är beroende av rhea-promise-biblioteket för att hantera anslutningar, skicka och ta emot meddelanden via AMQP-protokollet .

Logging

Du kan ange följande miljövariabel för att hämta felsökningsloggarna när du använder det här biblioteket.

  • Hämta felsökningsloggar från Service Bus SDK
export DEBUG=azure*
  • Hämta felsökningsloggar från Service Bus SDK och biblioteket på protokollnivå.
export DEBUG=azure*,rhea*
  • Om du inte är intresserad av att visa meddelandetransformeringen (som förbrukar mycket konsol-/diskutrymme) kan du ange miljövariabeln DEBUG på följande sätt:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Om du bara är intresserad av fel kan du ange miljövariabeln på DEBUG följande sätt:
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Logga in på en fil

  1. Ställ in miljövariabeln DEBUG som visas ovan
  2. Kör testskriptet på följande sätt:
  • Loggningsuttryck från testskriptet går till out.log och loggningsuttryck från sdk går till debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Loggningsinstruktioner från testskriptet och sdk:t går till samma fil out.log genom att omdirigera stderr till stdout (&1) och sedan omdirigera stdout till en fil: 
    node your-test-script.js >out.log 2>&1
  • Loggningsuttryck från testskriptet och sdk:t går till samma fil out.log. 
      node your-test-script.js &> out.log

Nästa steg

Ta en titt på exempelkatalogen för detaljerade exempel på hur du använder det här biblioteket för att skicka och ta emot meddelanden till/från Service Bus-köer, ämnen och prenumerationer.

Contributing

Om du vill bidra till detta bibliotek, läs gärna guiden bidrag för att lära dig mer om hur man bygger och testar koden.

  • Uppdaterades senast