Azure Service Bus client library for JavaScript - versie 7.10.0

Azure Service Bus is een zeer betrouwbare cloudberichtenservice van Microsoft.

Gebruik de clientbibliotheek @azure/service-bus in uw toepassing om

  • Berichten verzenden naar een Azure Service Bus-wachtrij of -onderwerp
  • Berichten ontvangen van een Azure Service Bus-wachtrij of -abonnement
  • Wachtrijen/onderwerpen/abonnementen/regels maken/verwijderen/bijwerken/weergeven in een Azure Service Bus-naamruimte.

Bronnen voor @azure/service-bus versie 7:

Sleutelkoppelingen:

OPMERKING: Als u versie 1.1.10 of lager gebruikt en wilt migreren naar de nieuwste versie van dit pakket, raadpleegt u onze migratiehandleiding om over te stappen van Service Bus V1 naar Service Bus V7

Aan de slag

Installeer het pakket

Installeer de nieuwste versie voor de Azure Service Bus-clientbibliotheek met behulp van npm.

npm install @azure/service-bus

Momenteel ondersteunde omgevingen

Prerequisites

TypeScript configureren

TypeScript-gebruikers moeten knooppunttypedefinities hebben geïnstalleerd:

npm install @types/node

U moet ook compilerOptions.allowSyntheticDefaultImports inschakelen in uw tsconfig.json. Houd er rekening mee dat als u compilerOptions.esModuleInterophebt ingeschakeld, allowSyntheticDefaultImports standaard is ingeschakeld. Zie het handboek voor compileropties van TypeScript voor meer informatie.

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

Naast wat daar wordt beschreven, heeft deze bibliotheek ook aanvullende polyfills nodig voor de volgende ingebouwde NodeJS-kernmodules om goed te kunnen werken in de browsers:

  • buffer
  • os
  • path
  • process

Bundeling met Webpack

Als u Webpack v5 gebruikt, kunt u de volgende dev-afhankelijkheden installeren

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

voeg vervolgens het volgende toe aan uw 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"),
+    },
   },

Bundeling met samenvouwen

Als u Rollup bundler gebruikt, installeert u de volgende dev-afhankelijkheden

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

Neem vervolgens het volgende op in uw 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"],
+    }),
  ]
};

Raadpleeg de documentatie van uw favoriete bundelaar voor meer informatie over het gebruik van polyfills.

React Native-ondersteuning

Net als bij browsers ondersteunt React Native sommige JavaScript-api's die door deze SDK-bibliotheek worden gebruikt niet, dus u moet er polyfills voor opgeven. Zie het voorbeeld van Messaging React Native met Expo voor meer informatie.

De client verifiëren

Interactie met Service Bus begint met een exemplaar van de ServiceBusClient-klasse . U kunt zich verifiëren bij Service Bus met behulp van een verbindingsreeks of met behulp van een Azure Active Directory-referentie.

Een verbindingsreeks gebruiken

Met deze methode wordt de verbindingsreeks naar uw Service Bus-exemplaar gebracht. U kunt de verbindingsreeks ophalen uit Azure Portal.

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

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

Meer informatie over deze constructor is beschikbaar in de API-documentatie.

Een Azure Active Directory-referentie gebruiken

Verificatie met Azure Active Directory maakt gebruik van de Azure Identity-bibliotheek.

In het onderstaande voorbeeld wordt gebruikgemaakt van de DefaultAzureCredential, een van de vele beschikbare referentieproviders uit de @azure/identity bibliotheek.

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

OPMERKING: Als u uw eigen implementatie van de TokenCredential interface tegen AAD gebruikt, stelt u de "scopes" voor servicebus in op het volgende om het juiste token te krijgen:

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

Meer informatie over deze constructor is beschikbaar in de API-documentatie

Belangrijke concepten

Nadat u een ServiceBusClienthebt geïnitialiseerd, kunt u met deze resources communiceren in een Service Bus-naamruimte:

  • Wachtrijen: Hiermee kunt u berichten verzenden en ontvangen. Vaak gebruikt voor point-to-point communicatie.
  • Onderwerpen: In tegenstelling tot wachtrijen zijn onderwerpen beter geschikt voor het publiceren/abonneren van scenario's. Een onderwerp kan worden verzonden naar, maar vereist een abonnement, waarvan er meerdere parallel kunnen zijn, om van te consumeren.
  • Abonnementen: het mechanisme om te consumeren vanuit een onderwerp. Elk abonnement is onafhankelijk en ontvangt een kopie van elk bericht dat naar het onderwerp wordt gestuurd. Regels en filters kunnen worden gebruikt om aan te passen welke berichten door een specifiek abonnement worden ontvangen.

Zie Wat is Azure Service Bus? voor meer informatie over deze resources.

Om met deze bronnen te kunnen communiceren, moet men bekend zijn met de volgende SDK-concepten:

Houd er rekening mee dat de wachtrijen, onderwerpen en abonnementen moeten worden gemaakt voordat u deze bibliotheek gebruikt.

Examples

De volgende secties bevatten codefragmenten die enkele van de veelvoorkomende taken dekken die gebruikmaken van Azure Service Bus

Berichten verzenden

Nadat u een exemplaar van een ServiceBusClient klasse hebt gemaakt, kunt u een ServiceBusSender krijgen met behulp van de createSender-methode die u kunt gebruiken om berichten te verzenden .

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

Berichten ontvangen

Nadat u een exemplaar van een ServiceBusClient klasse hebt gemaakt, kunt u een ServiceBusReceiver exemplaar verkrijgen met behulp van de createReceiver-methode .

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

Er zijn twee receiveModes beschikbaar.

  • "peekLock" - In de peekLock-modus heeft de ontvanger een vergrendeling op het bericht voor de duur die in de wachtrij is opgegeven.
  • 'receiveAndDelete': in de modus receiveAndDelete worden berichten verwijderd uit Service Bus zodra ze worden ontvangen.

Als de receiveMode niet is voorzien in de opties, wordt deze standaard ingesteld op de "peekLock"-modus. U kunt de ontvangen berichten ook afhandelen in de "peekLock"-modus.

U kunt deze ontvanger op een van de 3 manieren gebruiken om berichten te ontvangen:

Een scala aan berichten ophalen

Gebruik de functie receiveMessages die een belofte retourneert die wordt omgezet in een matrix van berichten.

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

Abonneren met behulp van een berichthandler

Gebruik de abonneringsmethode om berichthandlers in te stellen en deze zo lang te laten draaien als nodig is.

Als u klaar bent, belt receiver.close() u om geen berichten meer te ontvangen.

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

Asynchrone iterator gebruiken

Gebruik de getMessageIterator om een asynchrone iterator over berichten te krijgen

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
}

Een bericht afhandelen

Zodra u een bericht ontvangt, completeMessage()kunt u , , abandonMessage() of deferMessage() op de ontvanger bellen deadLetterMessage()op basis van hoe u het bericht wilt afhandelen.

Lees voor meer informatie Ontvangen berichten vereffenen

Wachtrijen voor ongeleverde berichten

De wachtrij voor dode letters is een subwachtrij. Elke wachtrij of elk abonnement heeft zijn eigen wachtrij voor onbestelbare berichten. In wachtrijen voor onbestelbare berichten worden berichten opgeslagen die expliciet zijn voorzien van dode letters (via receiver.deadLetterMessage()) of berichten waarvan het maximale aantal bezorgingen is overschreden.

Het maken van een ontvanger voor een subwachtrij voor onbestelbare berichten is vergelijkbaar met het maken van een ontvanger voor een abonnement of wachtrij:

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

Volledige voorbeelden die wachtrijen voor dode letters grondiger aantonen:

Berichten verzenden met behulp van Sessies

Voor het gebruik van sessies moet u een wachtrij of abonnement met sessieondersteuning maken. U kunt hier meer lezen over het configureren van deze functie in het portaal.

Als u berichten naar een sessie wilt verzenden, gebruikt u de ServiceBusClient om een afzender te maken met createSender.

Stel bij het verzenden van het bericht de sessionId eigenschap in het bericht in om ervoor te zorgen dat uw bericht in de juiste sessie terechtkomt.

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

Je kunt hier meer lezen over hoe sessies werken.

Berichten ontvangen van sessies

Voor het gebruik van sessies moet u een wachtrij of abonnement met sessieondersteuning maken. U kunt hier meer lezen over het configureren van deze functie in het portaal.

In tegenstelling tot wachtrijen of abonnementen die niet zijn ingeschakeld, kan slechts één ontvanger op elk moment uit een sessie lezen. Dit wordt afgedwongen door een sessie te vergrendelen , die wordt afgehandeld door Service Bus. Conceptueel is dit vergelijkbaar met hoe berichtvergrendeling werkt in de modus peekLock - wanneer een bericht (of sessie) is vergrendeld, heeft uw ontvanger er exclusieve toegang toe.

Als u een sessie wilt openen en vergrendelen, gebruikt u een exemplaar van ServiceBusClient om een SessionReceiver te maken.

Er zijn twee manieren om te kiezen welke sessie u wilt openen:

  1. Geef een sessionIdop waarmee een benoemde sessie wordt vergrendeld.

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

  2. Geef geen sessie-ID op. In dit geval zoekt Service Bus de volgende beschikbare sessie die nog niet is vergrendeld.

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

    Je kunt de naam van de sessie vinden via de sessionId property op de SessionReceiver. Als de receiveMode niet is voorzien in de opties, wordt deze standaard ingesteld op de "peekLock"-modus. U kunt de ontvangen berichten ook afhandelen in de "peekLock"-modus.

Zodra de ontvanger is aangemaakt, kunt u kiezen uit 3 manieren om berichten te ontvangen:

Je kunt hier meer lezen over hoe sessies werken.

Lijst met berichtsessies

Om te ontdekken welke sessies actieve berichten of de sessiestatus in een wachtrij of abonnement hebben, gebruik listMessageSessions()je :

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

Resources van een servicebus-naamruimte beheren

ServiceBusAdministrationClient kunt u een naamruimte beheren met CRUD-bewerkingen op de entiteiten (wachtrijen, onderwerpen en abonnementen) en op de regels van een abonnement.

  • Ondersteunt verificatie met een servicebusverbindingsreeks en met de AAD-referenties van @azure/identity vergelijkbaar met de ServiceBusClient.

Opmerking: Service Bus biedt nog geen ondersteuning voor het instellen van CORS-regels voor naamruimten, waardoor ServiceBusAdministrationClient het niet werkt in de browser zonder webbeveiliging uit te schakelen. Voor meer info, zie hier.

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

Probleemoplossingsproces

Hier zijn enkele eerste stappen om te beginnen met het diagnosticeren van problemen. Raadpleeg voor meer informatie de handleiding voor het oplossen van problemen met de Service Bus.

AMQP-afhankelijkheden

De Service Bus-bibliotheek is afhankelijk van de rhea-promise-bibliotheek voor het beheren van verbindingen en het verzenden en ontvangen van berichten via het AMQP-protocol .

Logging

U kunt de volgende omgevingsvariabele instellen om de logboeken voor foutopsporing op te halen bij het gebruik van deze bibliotheek.

  • Foutopsporingslogboeken ophalen van de Service Bus SDK
export DEBUG=azure*
  • Het ophalen van foutopsporingslogboeken van de Service Bus SDK en de bibliotheek op protocolniveau.
export DEBUG=azure*,rhea*
  • Als u niet geïnteresseerd bent in het bekijken van de berichttransformatie (die veel console-/schijfruimte in beslag neemt), kunt u de DEBUG omgevingsvariabele als volgt instellen:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Als u alleen geïnteresseerd bent in fouten, kunt u de DEBUG omgevingsvariabele als volgt instellen:
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Loggen naar een bestand

  1. Stel de DEBUG omgevingsvariabele in zoals hierboven weergegeven
  2. Voer uw testscript als volgt uit:
  • Logboekregistratie-instructies van uw testscript gaan naar out.log en logboekregistratie-instructies van de SDK gaan naar debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Logboekregistratie-instructies van uw testscript en de SDK gaan naar hetzelfde bestand out.log door stderr om te leiden naar stdout (&1) en leiden vervolgens stdout om naar een bestand: 
    node your-test-script.js >out.log 2>&1
  • Logboekregistratie-instructies van uw testscript en de SDK gaan naar hetzelfde bestand out.log. 
      node your-test-script.js &> out.log

Volgende stappen 

Neem een kijkje in de map met voorbeelden voor gedetailleerde voorbeelden van het gebruik van deze bibliotheek voor het verzenden en ontvangen van berichten van/naar Service Bus-wachtrijen, onderwerpen en abonnementen.

Contributing

Als je wilt bijdragen aan deze bibliotheek, lees dan de bijdragende gids om meer te weten te komen over hoe je de code bouwt en test.

  • Laatst bijgewerkt om