Azure Service Bus-Clientbibliothek für JavaScript – Version 7.9.5

Azure Service Bus ist ein äußerst zuverlässiger Cloudmessagingdienst von Microsoft.

Verwenden Sie die Clientbibliothek @azure/service-bus in Ihrer Anwendung, um

• Senden von Nachrichten an eine Azure Service Bus-Warteschlange oder ein Azure Service Bus-Thema
• Empfangen von Nachrichten aus einer Azure Service Bus-Warteschlange oder einem Azure Service Bus-Abonnement
• Erstellen/Get/Delete/Update/List Queues/Topics/Subscriptions/Rules in einem Azure Service Bus-Namespace.

Ressourcen für @azure/service-bus Version 7:

Wichtige Links:

• Quellcode
• Paket (npm)
• API-Referenzdokumentation
• Produktdokumentation
• Beispiele
• Handbuch zur Problembehandlung

HINWEIS: Wenn Sie Version 1.1.10 oder niedriger verwenden und zur neuesten Version dieses Pakets migrieren möchten, lesen Sie unseren Migrationsleitfaden, um von Service Bus V1 zu Service Bus V7 zu wechseln.

Erste Schritte

Installieren des Pakets

Installieren Sie die neueste Version für die Azure Service Bus-Clientbibliothek mithilfe von npm.

npm install @azure/service-bus

Die derzeitig unterstützten Umgebungen

• LTS-Versionen von Node.js

Voraussetzungen

• Ein Azure-Abonnement
• Ein Service Bus-Namespace

Konfigurieren von TypeScript

TypeScript-Benutzer müssen Knotentypdefinitionen installiert haben:

npm install @types/node

Sie müssen auch in Ihrem tsconfig.json aktivieren compilerOptions.allowSyntheticDefaultImports . Beachten Sie, dass , allowSyntheticDefaultImports wenn Sie aktiviert compilerOptions.esModuleInterophaben, standardmäßig aktiviert ist. Weitere Informationen finden Sie im Handbuch für Compileroptionen von TypeScript .

JavaScript-Bundle

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zunächst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

Zusätzlich zu dem, was dort beschrieben wird, benötigt diese Bibliothek auch zusätzliche Polyfills für die folgenden integrierten NodeJS-Core-Module, um in den Browsern ordnungsgemäß zu funktionieren:

• buffer
• os
• path
• process

Bündelung mit Webpack

Wenn Sie Webpack v5 verwenden, können Sie die folgenden Dev-Abhängigkeiten installieren.

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

fügen Sie dann Folgendes zu Ihrem 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"),
+    },
   },

Bündelung mit Rollup

Wenn Sie rollup bundler verwenden, installieren Sie die folgenden Dev-Abhängigkeiten

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

Fügen Sie dann Folgendes in Ihre 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"],
+    }),
  ]
};

Weitere Informationen zur Verwendung von Polyfills finden Sie in der Dokumentation Ihres bevorzugten Bundlers.

React Native Support

Ähnlich wie Browser unterstützt React Native keine JavaScript-API, die von dieser SDK-Bibliothek verwendet wird, sodass Sie polyfills für sie bereitstellen müssen. Weitere Informationen finden Sie im Messaging React Native-Beispiel mit Expo .

Authentifizieren des Clients

Die Interaktion mit Service Bus beginnt mit einer Instanz der ServiceBusClient-Klasse . Sie können sich bei Service Bus mithilfe einer Verbindungszeichenfolge oder mit Azure Active Directory-Anmeldeinformationen authentifizieren.

Verwenden einer Verbindungszeichenfolge

Diese Methode übernimmt die Verbindungszeichenfolge zu Ihrer Service Bus-Instanz. Sie können diese Verbindungszeichenfolge aus dem Azure-Portal abrufen.

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

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

Weitere Informationen zu diesem Konstruktor finden Sie in der API-Dokumentation.

Verwenden von Azure Active Directory-Anmeldeinformationen

Die Authentifizierung mit Azure Active Directory verwendet die Azure Identity-Bibliothek.

Im folgenden Beispiel wird DefaultAzureCredential verwendet, einer von vielen verfügbaren Anmeldeinformationsanbietern aus der @azure/identity Bibliothek.

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

HINWEIS: Wenn Sie Ihre eigene Implementierung der TokenCredential Schnittstelle für AAD verwenden, legen Sie die "Bereiche" für Service-Bus auf Folgendes fest, um das entsprechende Token abzurufen:

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

Weitere Informationen zu diesem Konstruktor finden Sie in der API-Dokumentation.

Wichtige Begriffe

Nachdem Sie einen ServiceBusClientinitialisiert haben, können Sie mit diesen Ressourcen in einem Service Bus-Namespace interagieren:

• Warteschlangen: Ermöglicht das Senden und Empfangen von Nachrichten. Wird häufig für die Punkt-zu-Punkt-Kommunikation verwendet.
• Themen: Im Gegensatz zu Warteschlangen eignen sich Themen besser für Veröffentlichungs-/Abonnementszenarien. Ein Thema kann an gesendet werden, erfordert jedoch ein Abonnement, von dem mehrere parallel verwendet werden können.
• Abonnements: Der Mechanismus, der aus einem Thema verwendet werden soll. Jedes Abonnement ist unabhängig und erhält eine Kopie jeder Nachricht, die an das Thema gesendet wird. Mithilfe von Regeln und Filtern können Sie anpassen, welche Nachrichten von einem bestimmten Abonnement empfangen werden.

Weitere Informationen zu diesen Ressourcen finden Sie unter Was ist Azure Service Bus?.

Um mit diesen Ressourcen zu interagieren, sollten Sie mit den folgenden SDK-Konzepten vertraut sein:

• Senden von Nachrichten an eine Warteschlange oder ein Thema mithilfe von ServiceBusSender erstellt ServiceBusClient.createSender().
• Empfangen von Nachrichten aus einer Warteschlange oder einem Abonnement mithilfe eines ServiceBusReceiver mit ServiceBusClient.createReceiver()erstellt.
• Empfangen von Nachrichten von sitzungsfähigen Warteschlangen oder Abonnements mithilfe eines ServiceBusSessionReceiver mit oder ServiceBusClient.acceptNextSession()erstellten ServiceBusClient.acceptSession() .

Beachten Sie, dass die Warteschlangen, Themen und Abonnements vor der Verwendung dieser Bibliothek erstellt werden sollten.

Beispiele

In den folgenden Abschnitten finden Sie Codeausschnitte, die einige der häufigen Aufgaben mit Azure Service Bus behandeln.

• Senden von Nachrichten
• Empfangen von Nachrichten
• Nachricht abrechnen
• Warteschlangen für unzustellbare Nachrichten
• Senden von Nachrichten mithilfe von Sitzungen
• Empfangen von Nachrichten von Sitzungen
• Verwalten von Ressourcen eines Service Bus-Namespace
• Weitere Beispiele

Senden von Nachrichten

Nachdem Sie eine Instanz einer ServiceBusClient Klasse erstellt haben, können Sie eine ServiceBusSender mit der createSender-Methode abrufen, die Sie zum Senden von Nachrichten verwenden können.

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

Empfangen von Nachrichten

Nachdem Sie eine Instanz einer ServiceBusClient Klasse erstellt haben, können Sie mithilfe der createReceiver-Methode eine ServiceBusReceiver abrufen.

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

Es stehen zwei receiveModes zur Verfügung.

• "peekLock": Im peekLock-Modus verfügt der Empfänger über eine Sperre für die Nachricht für die in der Warteschlange angegebene Dauer.
• "receiveAndDelete": Im receiveAndDelete-Modus werden Nachrichten aus Service Bus gelöscht, während sie empfangen werden.

Wenn der receiveMode in den Optionen nicht bereitgestellt wird, wird standardmäßig der "peekLock"-Modus verwendet. Sie können auch die empfangenen Nachrichten im "peekLock"-Modus festlegen.

Sie können diesen Empfänger auf eine von drei Arten verwenden, um Nachrichten zu empfangen:

Abrufen eines Arrays von Nachrichten

Verwenden Sie die receiveMessages-Funktion , die eine Zusage zurückgibt, die in ein Array von Nachrichten aufgelöst wird.

const myMessages = await receiver.receiveMessages(10);

Abonnieren mithilfe eines Nachrichtenhandlers

Verwenden Sie die Subscribe-Methode , um Nachrichtenhandler einzurichten und so lange wie nötig auszuführen.

Wenn Sie fertig sind, rufen Sie auf receiver.close() , um keine weiteren Nachrichten mehr zu erhalten.

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

Verwenden des asynchronen Iterators

Verwenden sie getMessageIterator , um einen asynchronen Iterator für Nachrichten abzurufen.

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

Nachricht abrechnen

Sobald Sie eine Nachricht erhalten haben, können Sie , deferMessage()abandonMessage()oder deadLetterMessage() den Empfänger aufrufencompleteMessage(), je nachdem, wie Sie die Nachricht abrechnen möchten.

Weitere Informationen finden Sie unter Abgleichen empfangener Nachrichten.

Warteschlangen für unzustellbare Nachrichten

Die Warteschlange für unzustellbare Nachrichten ist eine Untergeordnete Warteschlange. Jede Warteschlange oder jedes Abonnement verfügt über eine eigene Warteschlange für unzustellbare Nachrichten. Warteschlangen für unzustellbare Nachrichten speichern Nachrichten, die explizit unzustellbare Nachrichten (über receiver.deadLetterMessage()) wurden, oder Nachrichten, die ihre maximale Zustellungsanzahl überschritten haben.

Das Erstellen eines Empfängers für eine Unterwarteschlange für unzustellbare Nachrichten ähnelt dem Erstellen eines Empfängers für ein Abonnement oder eine Warteschlange:

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

Vollständige Beispiele, die die Warteschlangen für unzustellbare Nachrichten gründlicher veranschaulichen:

• Verwenden von receiver.deadLetterMessage() zum expliziten Senden von Nachrichten an die Unterwarteschlange für unzustellbare Nachrichten
• Empfangen von Nachrichten aus der Unterwarteschlange für unzustellbare Nachrichten

Senden von Nachrichten mithilfe von Sitzungen

Wenn Sie Sitzungen verwenden, müssen Sie eine sitzungsfähige Warteschlange oder ein Abonnement erstellen. Weitere Informationen zum Konfigurieren dieses Features finden Sie hier im Portal.

Verwenden Sie zum Senden von Nachrichten an eine Sitzung, ServiceBusClient um mithilfe von createSender einen Absender zu erstellen.

Legen Sie beim Senden der Nachricht die sessionId -Eigenschaft in der Nachricht fest, um sicherzustellen, dass Ihre Nachricht in der richtigen Sitzung landet.

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

Weitere Informationen zur Funktionsweise von Sitzungen finden Sie hier.

Empfangen von Nachrichten von Sitzungen

Wenn Sie Sitzungen verwenden, müssen Sie eine sitzungsfähige Warteschlange oder ein Abonnement erstellen. Weitere Informationen zum Konfigurieren dieses Features finden Sie hier im Portal.

Im Gegensatz zu nicht sitzungsfähigen Warteschlangen oder Abonnements kann nur ein einzelner Empfänger jederzeit aus einer Sitzung lesen. Dies wird erzwungen, indem eine Sitzung gesperrt wird, die von Service Bus behandelt wird. Vom Konzept her ähnelt dies der Funktionsweise von Nachrichtensperren bei Verwendung des peekLock Modus: Wenn eine Nachricht (oder Sitzung) gesperrt ist, hat Ihr Empfänger exklusiven Zugriff darauf.

Um eine Sitzung zu öffnen und zu sperren, verwenden Sie eine Instanz von ServiceBusClient , um einen SessionReceiver zu erstellen.

Es gibt zwei Möglichkeiten, die zu öffnende Sitzung auszuwählen:

1. Geben Sie einen sessionIdan, der eine benannte Sitzung sperrt.

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

2. Geben Sie keine Sitzungs-ID an. In diesem Fall findet Service Bus die nächste verfügbare Sitzung, die noch nicht gesperrt ist.

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

   Sie finden den Namen der Sitzung über die sessionId -Eigenschaft im SessionReceiver. Wenn der receiveMode in den Optionen nicht bereitgestellt wird, wird standardmäßig der "peekLock"-Modus verwendet. Sie können auch die empfangenen Nachrichten im "peekLock"-Modus abgleichen.

Nachdem der Empfänger erstellt wurde, können Sie zwischen drei Möglichkeiten zum Empfangen von Nachrichten wählen:

• Abrufen eines Arrays von Nachrichten
• Abonnieren mithilfe eines Nachrichtenhandlers
• Verwenden eines asynchronen Iterators

Weitere Informationen zur Funktionsweise von Sitzungen finden Sie hier.

Verwalten von Ressourcen eines Service Bus-Namespace

ServiceBusAdministrationClient mit können Sie einen Namespace mit CRUD-Vorgängen für die Entitäten (Warteschlangen, Themen und Abonnements) und für die Regeln eines Abonnements verwalten.

• Unterstützt die Authentifizierung mit einer Service Bus-Verbindungszeichenfolge sowie mit den AAD-Anmeldeinformationen von @azure/identity ähnlich wie ServiceBusClient.

Hinweis: Service Bus unterstützt das Festlegen von CORS-Regeln für Namespaces noch nicht und funktioniert daher ServiceBusAdministrationClient im Browser nicht, ohne die Websicherheit zu deaktivieren. Weitere Informationen finden Sie hier.

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

• Beispiel für Referenz : administrationClient.ts

Problembehandlung

Im Folgenden finden Sie einige erste Schritte, um mit der Diagnose von Problemen zu beginnen. Weitere Informationen finden Sie im Service Bus-Leitfaden zur Problembehandlung.

AMQP-Abhängigkeiten

Die Service Bus-Bibliothek hängt von der rhea-promise-Bibliothek ab, um Verbindungen zu verwalten, Nachrichten über das AMQP-Protokoll zu senden und zu empfangen.

Protokollierung

Sie können die folgende Umgebungsvariable festlegen, um Debugprotokolle anzuzeigen, wenn Sie diese Bibliothek verwenden.

• Abrufen von Debugprotokollen aus dem Service Bus SDK

export DEBUG=azure*

• Abrufen von Debugprotokollen aus dem Service Bus SDK und der Bibliothek auf Protokollebene.

export DEBUG=azure*,rhea*

• Wenn Sie nicht daran interessiert sind, die Nachrichtentransformation anzuzeigen (die viel Konsolen-/Datenträgerspeicherplatz beansprucht), können Sie die DEBUG Umgebungsvariable wie folgt festlegen:

export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer

• Wenn Sie nur an Fehlern interessiert sind, können Sie die DEBUG Umgebungsvariable wie folgt festlegen:

export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Protokollierung in einer Datei

1. Festlegen der Umgebungsvariablen DEBUG wie oben gezeigt
2. Führen Sie ihr Testskript wie folgt aus:

• Protokollierungsanweisungen aus Ihrem Testskript wechseln zu out.log , und Protokollierungsanweisungen aus dem SDK wechseln zu debug.log.

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

• Protokollierungsanweisungen aus Ihrem Testskript und dem SDK wechseln zu derselben Datei out.log , indem sie stderr zu stdout (&1) umleiten und dann stdout in eine Datei umleiten:

  node your-test-script.js >out.log 2>&1
  

• Protokollierungsanweisungen aus Ihrem Testskript und dem SDK wechseln zu derselben Datei out.log.

    node your-test-script.js &> out.log
  

Nächste Schritte

Im Beispielverzeichnis finden Sie ausführliche Beispiele für die Verwendung dieser Bibliothek zum Senden und Empfangen von Nachrichten an service Bus-Warteschlangen, -Themen und -Abonnements.

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.