Sdílet prostřednictvím

Klientská knihovna Azure Service Bus pro JavaScript – verze 7.9.5

  • Článek

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

Použít klientskou knihovnu @azure/service-bus ve vaší aplikaci

  • Odesílání zpráv do fronty nebo tématu služby Azure Service Bus
  • Příjem zpráv z fronty služby Azure Service Bus nebo předplatného
  • Vytváření,získání/odstranění/aktualizace/výpis front/témat/předplatných/pravidel v oboru názvů služby Azure Service Bus

Zdroje informací 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, projděte si našeho průvodce migrací a přejděte ze služby Service Bus V1 na Service Bus V7.

Začínáme

Instalace balíčku

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

npm install @azure/service-bus

Aktuálně podporovaná prostředí

Požadavky

Konfigurace TypeScriptu

Uživatelé TypeScriptu musí mít nainstalované definice typů uzlů:

npm install @types/node

Musíte také povolit compilerOptions.allowSyntheticDefaultImports v 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 k možnostem kompilátoru TypeScriptu .

JavaScript Bundle

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

Kromě toho, co je zde popsáno, potřebuje tato knihovna také další polyfills pro následující předdefinované moduly jádra NodeJS, aby mohla správně fungovat 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ývojové závislosti.

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

a pak do 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 kumulativní aktualizací

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

Pak do rollup.config.js uveď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ů najdete v dokumentaci k vašemu oblíbenému balíkovači.

Nativní podpora React

React Native podobně jako prohlížeče nepodporuje některé javascriptové rozhraní API používané touto knihovnou sady SDK, takže pro ně musíte poskytnout polyfills. 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 přihlašovacích údajů Azure Active Directory.

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

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

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

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

Další informace o tomto konstruktoru jsou k dispozici v dokumentaci k rozhraní API.

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

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

V následujícím příkladu se používá DefaultAzureCredential, jeden z mnoha dostupných zprostředkovatelů přihlašovacích údajů z @azure/identity knihovny.

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

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

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

Další informace o tomto konstruktoru jsou k dispozici v dokumentaci k rozhraní API.

Klíčové koncepty

Jakmile inicializujete ServiceBusClientobjekt , můžete s těmito prostředky pracovat v rámci oboru názvů služby Service Bus:

  • Fronty: Umožňuje odesílat a přijímat zprávy. Často se používá pro komunikaci typu point-to-point.
  • Témata: Na rozdíl od front jsou témata vhodnější pro scénáře publikování a odběru. Téma je možné odeslat na adresu, ale vyžaduje předplatné, jehož souběžné využití může být více.
  • Předplatná: Mechanismus, který se má využívat z tématu. Každé předplatné je nezávislé a obdrží kopii každé zprávy odeslané do tématu. Pravidla a filtry můžete použít k přizpůsobení zpráv přijatých konkrétním předplatným.

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

Pokud chcete s těmito prostředky pracovat, měli byste znát následující koncepty sady SDK:

Upozorňujeme, že fronty, témata a předplatná by se měly vytvořit před použitím této knihovny.

Příklady

Následující části obsahují fragmenty kódu, které pokrývají některé běžné úlohy s využitím služby Azure Service Bus.

Odesílání zpráv

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

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 ServiceBusReceiver pomocí metody createReceiver .

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

K dispozici jsou dvě receiveModemožnosti.

  • "peekLock" – v režimu peekLock má příjemce u zprávy zámek po dobu určenou ve frontě.
  • "receiveAndDelete" – v režimu receiveAndDelete se zprávy odstraňují ze služby Service Bus při jejich přijetí.

Pokud není v možnostech k dispozici režim receiveMode, ve výchozím nastavení se nastaví režim peekLock. Přijaté zprávy můžete také vyřešit v režimu "peekLock".

Tento příjemce můžete použít jedním ze 3 způsobů, jak přijímat zprávy:

Získání pole zpráv

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

const myMessages = await receiver.receiveMessages(10);

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

Pomocí metody přihlášení k odběru nastavte obslužné rutiny zpráv a nechte ji běžet tak dlouho, jak potřebujete.

Až budete hotovi, zavolejte, receiver.close() abyste přestali dostávat další zprávy.

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í getMessageIteratoru k získání asynchronního iterátoru pro zprávy

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

Vyřešení zprávy

Jakmile obdržíte zprávu, můžete na příjemce volat completeMessage(), abandonMessage()deferMessage() nebo deadLetterMessage() na základě toho, jak chcete zprávu vyřešit.

Další informace najdete v článku Vyrovnání přijatých zpráv.

Fronty nedoručených zpráv

Fronta nedoručených zpráv je dílčí fronta. Každá fronta nebo předplatné mají vlastní frontu nedoručených zpráv. Fronty nedoručených zpráv ukládají zprávy, které byly explicitně nedoručené (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 zpráv se podobá vytvoření příjemce pro předplatné nebo frontu:

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

Úplné ukázky demonstrující důkladnější fronty nedoručených zpráv:

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

Použití relací vyžaduje, abyste vytvořili frontu nebo předplatné s povolenou relací. Další informace o konfiguraci této funkce na portálu najdete tady.

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

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

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

Další informace o tom, jak relace fungují, najdete tady.

Příjem zpráv z relací

Použití relací vyžaduje, abyste vytvořili frontu nebo předplatné s povolenou relací. Další informace o konfiguraci této funkce na portálu najdete tady.

Na rozdíl od front nebo předplatných bez povolení relací může z relace kdykoli číst jenom jeden příjemce. To se vynucuje uzamčením relace, kterou zpracovává Service Bus. Koncepčně se to podobá tomu, jak funguje zamykání zpráv při použití peekLock režimu – když je zpráva (nebo relace) uzamčená, má k ní příjemce výhradní přístup.

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

Existují dva způsoby, jak zvolit, která relace se má otevřít:

  1. sessionIdZadejte , který uzamkne pojmenovanou relaci.

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

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

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

    Název relace můžete najít prostřednictvím sessionId vlastnosti na .SessionReceiver Pokud není v možnostech k dispozici režim receiveMode, ve výchozím nastavení se nastaví režim peekLock. Přijaté zprávy můžete také vyřešit v režimu "peekLock".

Po vytvoření příjemce si můžete vybrat ze 3 způsobů, jak přijímat zprávy:

Další informace o tom, jak relace fungují, najdete tady.

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

ServiceBusAdministrationClient umožňuje spravovat obor názvů s operacemi CRUD v entitách (frontách, tématech a předplatných) a v pravidlech předplatného.

  • Podporuje ověřování pomocí připojovacího řetězce služby Service Bus a také pomocí přihlašovacích údajů AAD podobných @azure/identityServiceBusClientjako .

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

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

Poradce při potížích

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

Závislosti AMQP

Knihovna služby 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 .

protokolování

Pokud chcete při použití této knihovny získat protokoly ladění, můžete nastavit následující proměnnou prostředí.

  • 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 vás nezajímá zobrazení transformace zpráv (která spotřebovává hodně místa na konzole nebo disku), můžete proměnnou DEBUG prostředí nastavit následujícím způsobem:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Pokud vás zajímají jenom chyby, můžete proměnnou DEBUG prostředí nastavit následujícím způsobem:
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. DEBUG Nastavení proměnné prostředí, jak je znázorněno výše
  2. Spusťte testovací skript následujícím způsobem:
  • Příkazy protokolování z testovacího skriptu se přejdou na out.log a příkazy protokolování ze sady SDK do debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Příkazy protokolování z testovacího skriptu a sady SDK přesměrují stderr na stdout (&1) do stejného souboru out.log a pak přesměrují stdout do souboru:
    node your-test-script.js >out.log 2>&1
  • Příkazy protokolování z testovacího skriptu a sady SDK přejdou do stejného souboru out.log. 
      node your-test-script.js &> out.log

Další kroky

Podrobné příklady použití této knihovny k odesílání a přijímání zpráv do a z front, témat a předplatných služby Service Bus najdete v adresáři samples.

Přispívání

Pokud chcete přispívat 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 sestavit a otestovat kód.

Imprese