Azure Service Bus-klientbibliotek för JavaScript – version 7.9.5

Azure Service Bus är en mycket tillförlitlig molnmeddelandetjänst 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:

• Källkod
• Paket (npm)
• API-referensdokumentation
• Produktdokumentation
• Exempel
• Felsökningsguide

Obs! Om du använder version 1.1.10 eller senare och vill migrera till den senaste versionen av det här paketet kan du titta på migreringsguiden för att gå 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 npm.

npm install @azure/service-bus

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

• LTS-versioner av Node.js

Förutsättningar

• En Azure-prenumeration
• Ett Service Bus-namnområde

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.esModuleInteropallowSyntheticDefaultImports är aktiverad 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.

Utöver vad som beskrivs där behöver det här biblioteket även ytterligare polyfiller för följande inbyggda NodeJS-kärnmoduler för att fungera korrekt i webbläsaren:

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

Paketering 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 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.

React Native Support

På samma sätt som i webbläsare stöder React Native inte vissa JavaScript-API:er som används av det här SDK-biblioteket, så du måste ange polyfiller för dem. Mer information finns i Det inbyggda exemplet Messaging React med Expo .

Autentisera klienten

Interaktion med Service Bus börjar med en instans av klassen ServiceBusClient . Du kan autentisera till Service Bus med hjälp av en anslutningssträng eller med hjälp av en Azure Active Directory-autentiseringsuppgift.

Använda en anslutningssträng

Den här metoden tar anslutningssträngen till din Service Bus-instans. Du kan hämta anslutningssträngen från Azure-portalen.

const { ServiceBusClient } = require("@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.

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

Obs! 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 hämta 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: Tillåter att meddelanden skickas och tas emot. Används ofta för punkt-till-punkt-kommunikation.
• Ämnen: Till skillnad från köer är ämnen bättre lämpade för publicerings-/prenumerationsscenarier. Ett ämne kan skickas till, men kräver en prenumeration, där det kan finnas flera parallellt, att använda från.
• Prenumerationer: Mekanismen för att använda från ett ämne. Varje prenumeration är oberoende och tar emot 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?.

För att interagera med dessa resurser bör man känna till följande SDK-begrepp:

• Skicka meddelanden till en kö eller ett ämne med hjälp av en ServiceBusSender skapad med .ServiceBusClient.createSender()
• Ta emot meddelanden, antingen från en kö eller en prenumeration, med hjälp av en ServiceBusReceiver skapad med .ServiceBusClient.createReceiver()
• Ta emot meddelanden från sessionsaktiverade köer eller prenumerationer med hjälp av en ServiceBusSessionReceiver skapad med eller ServiceBusClient.acceptSession()ServiceBusClient.acceptNextSession().

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

Exempel

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

• Skicka meddelanden
• Ta emot meddelanden
• Reglera ett meddelande
• Köer med obeställbara meddelanden
• Skicka meddelanden med sessioner
• Ta emot meddelanden från sessioner
• Hantera resurser för ett Service Bus-namnområde
• Ytterligare exempel

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.

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 hämta en ServiceBusReceiver med metoden createReceiver .

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

Det finns två receiveModetillgängliga.

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

Om receiveMode inte anges i alternativen är det standardläget "peekLock". Du kan också reglera meddelandena som tas emot i "peekLock"-läge.

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

Hämta en matris med meddelanden

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

const myMessages = await receiver.receiveMessages(10);

Prenumerera med en meddelandehanterare

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

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

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

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

Reglera ett meddelande

När du får ett meddelande kan du anropa completeMessage(), abandonMessage()deferMessage() eller deadLetterMessage() på mottagaren baserat på hur du vill reglera meddelandet.

Mer information finns i Lösa mottagna meddelanden

Köer med obeställbara meddelanden

Kön med obeställbara meddelanden är en underkö. Varje kö eller prenumeration har en egen kö med obeställbara meddelanden. Köer med obeställbara meddelanden lagrar meddelanden som uttryckligen har varit obeställbara (via receiver.deadLetterMessage()) eller meddelanden som har överskridit det maximala leveransantalet.

Att skapa en mottagare för en obeställd delkö liknar att skapa en mottagare för en prenumeration eller kö:

// 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 med obeställbara meddelanden mer noggrant:

• Använda receiver.deadLetterMessage() för att uttryckligen skicka meddelanden till underkön för obeställbara meddelanden
• Ta emot meddelanden från delkön med obeställbara meddelanden

Skicka meddelanden med 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.

För att skicka meddelanden till en session använder du ServiceBusClient för att skapa en avsändare med createSender.

När du skickar meddelandet anger du sessionId egenskapen i meddelandet för att se till att meddelandet hamnar i rätt session.

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

Du kan läsa mer om hur sessioner 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 en session låses , vilket hanteras av Service Bus. Konceptuellt liknar detta hur meddelandelåsning fungerar när du använder peekLock läge – när ett meddelande (eller en session) är låst har mottagaren exklusiv åtkomst till det.

För att ö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 läget "peekLock". Du kan också reglera de meddelanden som tas emot i "peekLock"-läge.

När mottagaren har skapats kan du välja mellan tre olika sätt att ta emot meddelanden:

• Hämta en matris med meddelanden
• Prenumerera med hjälp av en meddelandehanterare
• Använda asynkron iterator

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

Hantera resurser för ett Service Bus-namnområde

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

• Stöder autentisering med en Service Bus-anslutningssträng samt med AAD-autentiseringsuppgifterna ServiceBusClientsom @azure/identity liknar .

Obs! Service Bus har inte stöd för att ange CORS-regler för namnområden ännu, och fungerar därför ServiceBusAdministrationClient inte i webbläsaren utan att webbsäkerhet inaktiveras. Mer information finns här.

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

• Exempel som referens – administrationClient.ts

Felsökning

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 .

Loggning

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 DEBUG miljövariabeln 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 DEBUG miljövariabeln på 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. DEBUG Ange miljövariabeln enligt ovan
2. Kör testskriptet på följande sätt:

• Loggningsuttryck från testskriptet går till out.log och loggningsuttryck från sdk:t går till debug.log.

  node your-test-script.js > out.log 2>debug.log
  

• Loggningsinstruktioner från testskriptet och sdk:en 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 och från Service Bus-köer, ämnen och prenumerationer.

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.