Azure Service Bus client library for JavaScript - version 7.10.0

Azure Service Bus je vysoce spolehlivá cloudová služba pro zasílání zpráv od Microsoftu.

Klientskou knihovnu @azure/service-bus ve své aplikaci použijte k následujícím účelům

  • Odesílání zpráv do fronty nebo tématu služby Azure Service Bus
  • Příjem zpráv z fronty nebo předplatného služby Azure Service Bus
  • Vytvářejte/získávejte/odstraňujte/aktualizujte/vypsávejte fronty/témata/předplatné/pravidla v oboru názvů Azure Service Bus.

Zdroje pro @azure/service-bus verzi 7:

Klíčové odkazy:

POZNÁMKA: Pokud používáte verzi 1.1.10 nebo nižší a chcete migrovat na nejnovější verzi tohoto balíčku, podívejte se na našeho průvodce migrací a přejděte ze služby Service Bus V1 na službu Service Bus V7.

Začínáme

Nainstalujte balíček

Nainstalujte nejnovější verzi klientské knihovny Azure Service Bus pomocí npm.

npm install @azure/service-bus

Aktuálně podporovaná prostředí

Prerequisites

Konfigurace TypeScriptu

Uživatelé TypeScriptu musí mít nainstalované definice typu Node:

npm install @types/node

Musíte také povolit compilerOptions.allowSyntheticDefaultImports ve svém tsconfig.json. Všimněte si, že pokud jste povolili compilerOptions.esModuleInterop, allowSyntheticDefaultImports je ve výchozím nastavení povolená. Další informace najdete v příručce možnosti kompilátoru TypeScriptu.

JavaScriptový balíček

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci sdružování.

Kromě toho, co je zde popsáno, potřebuje tato knihovna také další polyfilly pro následující vestavěné moduly jádra NodeJS, aby správně fungovala v prohlížečích:

  • buffer
  • os
  • path
  • process

Sdružování s webpackem

Pokud používáte Webpack v5, můžete nainstalovat následující vývojářské závislosti

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

Poté do svého webpack.config.js přidejte následující

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

Sdružování s funkcí Rollup

Pokud používáte nástroj Rollup Bundler, nainstalujte následující vývojové závislosti

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

Poté do svého rollup.config.js zahrňte následující

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

Další informace o používání polyfillů naleznete v dokumentaci vašeho oblíbeného balíčkáře.

Podpora React Native

Podobně jako prohlížeče ani React Native nepodporuje některá rozhraní API JavaScriptu používaná touto knihovnou SDK, takže pro ně musíte poskytnout polyfilly. Další podrobnosti najdete v ukázce Messaging React Native s Expo .

Ověření klienta

Interakce se službou Service Bus začíná instancí třídy ServiceBusClient . Ve službě Service Bus se můžete ověřit pomocí připojovacího řetězce nebo pomocí přihlašovacích údajů Azure Active Directory.

Použití připojovacího řetězce

Tato metoda převezme připojovací řetězec do vaší instance služby Service Bus. Připojovací řetězec můžete získat z webu Azure Portal.

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

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

Více informací o tomto konstruktoru je k dispozici v dokumentaci API.

Použití přihlašovacích údajů Azure Active Directory

Ověřování pomocí Azure Active Directory používá knihovnu Azure Identity.

Následující příklad používá DefaultAzureCredential, jednoho z mnoha dostupných poskytovatelů přihlašovacích údajů z @azure/identity knihovny.

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

POZNÁMKA: Pokud používáte vlastní implementaci TokenCredential rozhraní proti AAD, nastavte "obory" pro Service-Bus na následující, abyste získali příslušný token:

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

Více informací o tomto konstruktoru je k dispozici v dokumentaci k rozhraní API

Klíčové koncepty

Po inicializaci ServiceBusClientnástroje můžete s těmito prostředky pracovat v rámci oboru názvů služby Service Bus:

  • Fronty: Umožňuje odesílání a přijímání zpráv. Často se používá pro point-to-point komunikaci.
  • Témata: Na rozdíl od front jsou témata vhodnější pro scénáře publikování/odběru. Téma lze odeslat, ale vyžaduje předplatné, kterých může být paralelně několik, ze kterých lze využívat.
  • Odběry: Mechanismus pro využití z tématu. Každé přihlášení k odběru je nezávislé a obdrží kopii každé zprávy odeslané k tématu. Pravidla a filtry lze použít k přizpůsobení, které zprávy budou přijímány konkrétním předplatným.

Další informace o těchto zdrojích najdete v tématu Co je Azure Service Bus?.

Chcete-li pracovat s těmito zdroji, měli byste být obeznámeni s následujícími koncepty SDK:

Upozorňujeme, že fronty, témata a odběry by měly být vytvořeny před použitím této knihovny.

Examples

Následující části obsahují fragmenty kódu, které pokrývají některé běžné úlohy pomocí Azure Service Bus

Odesílání zpráv

Jakmile vytvoříte instanci ServiceBusClient třídy, můžete pomocí metody ServiceBusSender získat metodu, kterou můžete použít k odesílání zpráv.

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

Příjem zpráv

Jakmile vytvoříte instanci ServiceBusClient třídy, můžete získat metodu ServiceBusReceivercreateReceiver .

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

K dispozici jsou dvě receiveModevarianty.

  • "peekLock" - V režimu peekLock má příjemce zámek na zprávu po dobu určenou ve frontě.
  • "receiveAndDelete" – V režimu receiveAndDelete jsou zprávy odstraněny ze služby Service Bus při přijetí.

Pokud parametr receiveMode není v možnostech uveden, použije se jako výchozí režim "peekLock". Můžete také vypořádat zprávy přijaté v režimu "peekLock".

Tento přijímač můžete použít jedním ze 3 způsobů přijímání zpráv:

Získání pole zpráv

Použijte funkci receiveMessages , která vrací příslib, který se překládá na pole zpráv.

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

Přihlášení k odběru pomocí obslužné rutiny zprávy

Pomocí metody subscribe nastavte obslužné programy pro zpracování zpráv a nechte ji běžet tak dlouho, jak budete potřebovat.

Až budete hotovi, zavolejte receiver.close() a přestaňte dostávat další zprávy.

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

Použití asynchronního iterátoru

Použití getMessageIterator k získání asynchronního iterátoru nad zprávami

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
}

Vyřízení zprávy

Jakmile obdržíte zprávu, můžete zavolat completeMessage(), nebo abandonMessage() na sluchátko podle toho, deferMessage()deadLetterMessage() jak chcete zprávu vyřídit.

Více se dozvíte v článku Vypořádání přijatých zpráv

Fronty nedoručených zpráv

Fronta mrtvých dopisů je podfronta. Každá fronta nebo předplatné má svou vlastní frontu nedoručených zpráv. Fronty nedoručených zpráv ukládají zprávy, které byly explicitně odeslány nedoručenými dopisy (prostřednictvím receiver.deadLetterMessage()), nebo zprávy, které překročily maximální počet doručení.

Vytvoření příjemce pro dílčí frontu nedoručených dopisů je podobné vytvoření příjemce pro odběr nebo frontu:

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

Kompletní ukázky demonstrující fronty mrtvých dopisů důkladněji:

Odesílání zpráv pomocí relací

Použití relací vyžaduje, abyste vytvořili frontu nebo odběr s povolenou relací. Další informace o tom, jak tuto funkci nakonfigurovat na portálu najdete tady.

Chcete-li odesílat zprávy do relace, použijte k ServiceBusClient vytvoření odesílatele pomocí createSender.

Při odesílání zprávy nastavte sessionId vlastnost ve zprávě, abyste zajistili, že se vaše zpráva dostane do správné relace.

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

Více informací o tom, jak sezení fungují, si můžete přečíst zde.

Příjem zpráv ze zasedání

Použití relací vyžaduje, abyste vytvořili frontu nebo odběr s povolenou relací. Další informace o tom, jak tuto funkci nakonfigurovat na portálu najdete tady.

Na rozdíl od front nebo odběrů, které nejsou povoleny relacemi, může z relace v každém okamžiku číst pouze jeden příjemce. To se vynucuje uzamčením relace, kterou zpracovává Service Bus. Koncepčně je to podobné tomu, jak funguje zamykání zpráv při použití peekLock režimu - když je zpráva (nebo relace) uzamčena, váš příjemce k ní má výhradní přístup.

Chcete-li otevřít a uzamknout relaci, použijte instanci k ServiceBusClient vytvoření SessionReceiver.

Existují dva způsoby, jak zvolit, kterou relaci otevřít:

  1. Zadejte hodnotu , sessionIdkterá uzamkne pojmenovanou relaci.

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

  2. Nezadávejte ID relace. V takovém případě Service Bus najde další dostupnou relaci, která ještě není uzamčena.

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

    Název relace můžete zjistit pomocí sessionId vlastnosti na kartě SessionReceiver. Pokud parametr receiveMode není v možnostech uveden, použije se jako výchozí režim "peekLock". Můžete také vypořádat zprávy přijaté v režimu "peekLock".

Po vytvoření příjemce si můžete vybrat ze 3 způsobů přijímání zpráv:

Více informací o tom, jak sezení fungují, si můžete přečíst zde.

Vypsat relace zpráv

Chcete-li zjistit, které relace mají aktivní zprávy nebo stav relace ve frontě či odběru, použijte 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);
}

Správa prostředků oboru názvů služby Service Bus

ServiceBusAdministrationClient umožňuje spravovat obor názvů s operacemi CRUD s entitami (frontami, tématy a předplatnými) a s pravidly předplatného.

  • Podporuje ověřování pomocí připojovacího řetězce sběrnice Service Bus a také pomocí přihlašovacích údajů AAD z @azure/identity podobného rozhraní ServiceBusClient.

Poznámka: Služba Service Bus zatím nepodporuje nastavení pravidel CORS pro obory názvů, a proto ServiceBusAdministrationClient nebude v prohlížeči fungovat bez zakázání zabezpečení webu. Další informace naleznete zde.

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

Zde je několik počátečních kroků, jak začít diagnostikovat problémy. Další informace se nacházejí v Průvodci odstraňováním potíží se službou Service Bus.

Závislosti AMQP

Knihovna Service Bus závisí na knihovně rhea-promise pro správu připojení, odesílání a přijímání zpráv přes protokol AMQP .

Logging

Následující proměnnou prostředí můžete nastavit, abyste při používání této knihovny získali protokoly ladění.

  • Získání protokolů ladění ze sady Service Bus SDK
export DEBUG=azure*
  • Získání protokolů ladění ze sady Service Bus SDK a knihovny na úrovni protokolu.
export DEBUG=azure*,rhea*
  • Pokud nemáte zájem o zobrazení transformace zprávy (která spotřebovává hodně místa v konzole/disku), můžete nastavit proměnnou DEBUG prostředí následovně:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Pokud vás zajímají pouze chyby, pak můžete proměnnou DEBUG prostředí nastavit následovně:
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Protokolování do souboru

  1. Nastavte proměnnou prostředí, DEBUG jak je uvedeno výše
  2. Spusťte testovací skript následujícím způsobem:
  • Příkazy protokolování z testovacího skriptu přejděte na out.log a příkazy protokolování ze sady SDK přejděte na debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Příkazy protokolování z testovacího skriptu a sady SDK se přesměrují do stejného souboru out.log přesměrováním stderru na stdout (&1) a pak přesměrují stdout na soubor: 
    node your-test-script.js >out.log 2>&1
  • Příkazy protokolování z testovacího skriptu a sada SDK přejdou do stejného souboru out.log. 
      node your-test-script.js &> out.log

Další kroky

Podívejte se prosím do adresáře s ukázkami , kde najdete podrobné příklady, jak tuto knihovnu používat k odesílání a přijímání zpráv do/z front, témat a předplatných služby Service Bus.

Contributing

Pokud byste chtěli přispět do této knihovny, přečtěte si prosím průvodce přispívání kde se dozvíte více o tom, jak kód sestavit a testovat.

  • Poslední aktualizace v