Delen via

Azure Service Bus clientbibliotheek voor JavaScript - versie 7.9.4

  • Artikel

Azure Service Bus is een uiterst 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
  • Maken/ophalen/verwijderen/bijwerken/wachtrijen/onderwerpen/abonnementen/regels in een Azure Service Bus naamruimte.

Resources voor @azure/service-bus versie 7:

Belangrijke koppelingen:

OPMERKING: Als u versie 1.1.10 of lager gebruikt en wilt migreren naar de nieuwste versie van dit pakket, raadpleegt u onze migratiehandleiding voor het overstappen van Service Bus V1 naar Service Bus V7

Aan de slag

Het pakket installeren

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

npm install @azure/service-bus

Momenteel ondersteunde omgevingen

Vereisten

TypeScript configureren

TypeScript-gebruikers moeten knooppunttypedefinities hebben geïnstalleerd:

npm install @types/node

U moet ook inschakelen compilerOptions.allowSyntheticDefaultImports in uw tsconfig.json. Houd er rekening mee dat als u hebt ingeschakeld compilerOptions.esModuleInterop, 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 bundler gebruiken. Raadpleeg onze bundeldocumentatie voor 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

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

Bundelen met rollup

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 biedt React Native geen ondersteuning voor bepaalde JavaScript-API's die door deze SDK-bibliotheek worden gebruikt. Daarom moet u polyfills voor deze api's opgeven. Zie het Voorbeeld van berichten React Native met Expo voor meer informatie.

De client verifiëren

Interactie met Service Bus begint met een exemplaar van de klasse ServiceBusClient . U kunt zich bij Service Bus verifiëren 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 uitgevoerd. U kunt de verbindingsreeks ophalen uit de Azure Portal.

const { ServiceBusClient } = require("@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 de DefaultAzureCredential gebruikt, een van de vele beschikbare referentieproviders uit de @azure/identity bibliotheek.

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

OPMERKING: als u uw eigen implementatie van de TokenCredential interface voor AAD gebruikt, stelt u de bereiken voor service bus in op het volgende om het juiste token op te halen:

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

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

Belangrijkste concepten

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

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

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

Als u met deze resources wilt werken, moet u 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.

Voorbeelden

De volgende secties bevatten codefragmenten die betrekking hebben op enkele van de algemene taken met behulp van Azure Service Bus

Berichten verzenden

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

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 ophalen met behulp van de methode createReceiver .

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 is opgegeven in de wachtrij.
  • 'receiveAndDelete' - In de modus receiveAndDelete worden berichten verwijderd uit Service Bus zodra ze worden ontvangen.

Als de receiveMode niet is opgegeven in de opties, wordt standaard de modus peekLock gebruikt. U kunt de ontvangen berichten ook vereffenen in de modus peekLock.

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

Een matrix met berichten ophalen

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

const myMessages = await receiver.receiveMessages(10);

Abonneren met een berichtenhandler

Gebruik de methode abonneren om berichthandlers in te stellen en deze zo lang als nodig uit te voeren.

Wanneer u klaar bent, roept receiver.close() u aan om geen berichten meer te ontvangen.

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

GetMessageIterator gebruiken om een asynchrone iterator over berichten op te halen

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

Een bericht vereffenen

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

Lees Ontvangen berichten afhandelen voor meer informatie

Wachtrijen met onbestelbare berichten

De wachtrij met onbestelbare berichten is een subwachtrij. Elke wachtrij of elk abonnement heeft een eigen wachtrij met onbestelbare berichten. In wachtrijen voor onbestelbare berichten worden berichten opgeslagen die expliciet in de wachtrij zijn geplaatst (via receiver.deadLetterMessage()), of berichten die het maximale aantal bezorgingen hebben overschreden.

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

// 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 waarin wachtrijen met onbestelbare berichten grondiger worden gedemonstreerd:

Berichten verzenden met behulp van sessies

Voor het gebruik van sessies moet u een wachtrij of abonnement maken waarvoor een sessie is ingeschakeld. U kunt hier meer lezen over het configureren van deze functie in de portal.

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

Wanneer u het bericht verzendt, stelt u de sessionId eigenschap in het bericht in om ervoor te zorgen dat uw bericht in de juiste sessie terechtkomt.

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

U kunt hier meer lezen over hoe sessies werken.

Berichten ontvangen van sessies

Voor het gebruik van sessies moet u een wachtrij of abonnement maken waarvoor een sessie is ingeschakeld. U kunt hier meer lezen over het configureren van deze functie in de portal.

In tegenstelling tot wachtrijen of abonnementen zonder sessie kan slechts één ontvanger op elk gewenst moment een sessie lezen. Dit wordt afgedwongen door een sessie te vergrendelen , die wordt verwerkt door Service Bus. Conceptueel is dit vergelijkbaar met hoe berichtvergrendeling werkt wanneer de peekLock modus wordt gebruikt: wanneer een bericht (of sessie) is vergrendeld, heeft de 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 vindt Service Bus de volgende beschikbare sessie die nog niet is vergrendeld.

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

    U vindt de naam van de sessie via de sessionId eigenschap op de SessionReceiver. Als de receiveMode niet is opgegeven in de opties, wordt standaard de modus peekLock gebruikt. U kunt de ontvangen berichten ook vereffenen in de modus peekLock.

Zodra de ontvanger is gemaakt, kunt u kiezen uit drie manieren om berichten te ontvangen:

U kunt hier meer lezen over hoe sessies werken.

Resources van een Service Bus-naamruimte beheren

ServiceBusAdministrationClient hiermee 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 Service Bus-verbindingsreeks 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 en werkt daarom ServiceBusAdministrationClient niet in de browser zonder webbeveiliging uit te schakelen. Kijk hier voor meer informatie.

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

Problemen oplossen

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

AMQP-afhankelijkheden

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

Logboekregistratie

U kunt de volgende omgevingsvariabele instellen om de foutopsporingslogboeken op te halen wanneer u deze bibliotheek gebruikt.

  • Logboeken voor foutopsporing ophalen uit de Service Bus SDK
export DEBUG=azure*
  • Logboeken voor foutopsporing ophalen van de Service Bus SDK en de bibliotheek op protocolniveau.
export DEBUG=azure*,rhea*
  • Als u niet geïnteresseerd bent in het weergeven van de berichttransformatie (die veel console-/schijfruimte verbruikt), 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

Logboekregistratie bij een bestand

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

Volgende stappen

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

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.

Weergaven