Azure Service Bus klientské knihovny pro JavaScript – verze 7.9.4

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

Pomocí klientské knihovny @azure/service-bus ve vaší aplikaci

• Odeslání zpráv do fronty nebo tématu Azure Service Bus
• Příjem zpráv z fronty Azure Service Bus nebo odběru
• Vytváření,získání/odstranění/aktualizace/výpisu front/témat/odběrů/pravidel v oboru názvů Azure Service Bus.

Prostředky pro @azure/service-bus verzi 7:

Klíčové odkazy:

• Zdrojový kód
• Balíček (npm)
• Referenční dokumentace k rozhraní API
• Produktová dokumentace
• ukázky
• Průvodce odstraňováním potíží

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 Azure Service Bus pomocí npm.

npm install @azure/service-bus

Aktuálně podporovaná prostředí

• LtS verze Node.js

Požadavky

• Předplatné Azure
• Obor názvů služby Service Bus

Konfigurace TypeScriptu

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

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 k možnostem kompilátoru TypeScriptu .

JavaScript Bundle

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

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

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

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 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í polyfills najdete v dokumentaci k vašemu oblíbenému bundleru.

Podpora React Native

Podobně jako u prohlížečů React Native 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 React Native zasílání zpráv s expo.

Ověření klienta

Interakce se službou Service Bus začíná instancí třídy ServiceBusClient . K ověření ve službě Service Bus můžete použít připojovací řetězec nebo přihlašovací údaje Azure Active Directory.

Použití připojovací řetězec

Tato metoda přenese připojovací řetězec do instance služby Service Bus. Připojovací řetězec můžete získat z 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 Azure Identity Library.

Následující příklad používá DefaultAzureCredential, jednoho z mnoha dostupných zprostředkovatelů přihlašovacích @azure/identity údajů z 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 ServiceBusClient, 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říjem zpráv. Č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 odběr, jehož odběr může být paralelně více.
• Odběry: Mechanismus pro využívání z tématu. Každý odběr je nezávislý a obdrží kopii každé zprávy odeslané do tématu. Pravidla a filtry se dají použít k přizpůsobení toho, které zprávy mají být přijímány konkrétním odběrem.

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:

• Odesílání zpráv do fronty nebo tématu pomocí nástroje vytvořeného ServiceBusSender pomocí ServiceBusClient.createSender().
• Příjem zpráv z fronty nebo odběru pomocí objektu vytvořeného ServiceBusReceiver pomocí ServiceBusClient.createReceiver().
• Příjem zpráv z front nebo odběrů s povolenými relacemi pomocí vytvořeného ServiceBusSessionReceiver pomocí ServiceBusClient.acceptSession() nebo ServiceBusClient.acceptNextSession().

Upozorňujeme, že fronty, témata a odběry 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 pomocí Azure Service Bus

• Odesílání zpráv
• Příjem zpráv
• Vyřešení zprávy
• Fronty nedoručených zpráv
• Odesílání zpráv pomocí relací
• Příjem zpráv z relací
• Správa prostředků oboru názvů služby Service Bus
• Další ukázky

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 uvedenou ve frontě.
• "receiveAndDelete" – v režimu receiveAndDelete se zprávy ze služby Service Bus odstraňují při jejich přijetí.

Pokud není v možnostech k dispozici režim receiveMode, nastaví se výchozí 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řeloží 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 je běžet tak dlouho, jak potřebujete.

Až budete hotovi, zavolejte receiver.close() , abyste přestali přijímat 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í getMessageIterator 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 volat completeMessage(), abandonMessage()nebo deadLetterMessage() na příjemce podle toho, deferMessage() 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 odběr má 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 pod frontu nedoručených zpráv je podobné jako vytvoření příjemce pro odběr 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, které důkladněji demonstrují fronty nedoručených zpráv:

• Použití metody receiver.deadLetterMessage() k explicitní odesílání zpráv do pod fronty nedoručených zpráv
• Příjem zpráv z pod 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 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 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 pouze jeden příjemce. To se vynucuje uzamčením relace, kterou zpracovává Služba 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čená, má k ní příjemce výhradní přístup.

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

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

1. Zadejte , sessionIdkterý 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í zamknutá.

   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, nastaví se výchozí 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 mezi 3 způsoby příjmu zpráv:

• Získání pole zpráv
• Přihlášení k odběru pomocí obslužné rutiny zprávy
• Použití asynchronního iterátoru

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 s entitami (frontami, tématy a odběry) a pravidly předplatného.

• Podporuje ověřování pomocí služby Service Bus připojovací řetězec a také s přihlašovacími údaji AAD z @azure/identity podobně jako .ServiceBusClient

Poznámka: Service Bus zatím nepodporuje nastavení pravidel CORS pro obory názvů, a 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);

• Ukázka pro referenci – administrationClient.ts

Poradce při potížích

Tady je několik počátečních kroků pro zahájení diagnostiky problémů. Další informace najdete 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 .

protokolování

Pokud použijete tuto knihovnu, můžete nastavit následující proměnnou prostředí, abyste 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 SDK služby Service Bus 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 na konzole nebo na 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. Nastavte proměnnou DEBUG 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 přejdou do out.log a příkazy protokolování ze sady SDK se přejdou 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řejdou do stejného souboru out.log přesměrováním stderru na stdout (&1) 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 odběrů 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 příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.