Azure Service Bus ügyfélkódtár JavaScripthez – 7.9.5-ös verzió

Az Azure Service Bus a Microsoft megbízható felhőalapú üzenetkezelési szolgáltatása.

Az alkalmazás ügyfélkódtárának @azure/service-bus használatával

• Üzenetek küldése Azure Service Bus-üzenetsorba vagy -témakörbe
• Üzenetek fogadása Azure Service Bus-üzenetsorból vagy előfizetésből
• Create/Get/Delete/Update/List Queues/Topics/Subscriptions/Rules in an Azure Service Bus namespace ..

A 7-es verzió erőforrásai @azure/service-bus :

Fő hivatkozások:

• Forráskód
• Csomag (npm)
• API-referenciadokumentáció
• Termékdokumentáció
• Példák
• Hibaelhárítási útmutató

MEGJEGYZÉS: Ha az 1.1.10-es vagy újabb verziót használja, és a csomag legújabb verziójára szeretne migrálni, tekintse meg migrálási útmutatónkat a Service Bus V1-ről a Service Bus V7-es verzióra való áttéréshez

Első lépések

A csomag telepítése

Telepítse az Azure Service Bus-ügyfélkódtár legújabb verzióját az npm használatával.

npm install @azure/service-bus

Jelenleg támogatott környezetek

• A Node.jsLTS-verziói

Előfeltételek

• Azure-előfizetés
• Service Bus-névtér

TypeScript konfigurálása

A TypeScript-felhasználóknak csomóponttípus-definíciókat kell telepíteniük:

npm install @types/node

A tsconfig.json is engedélyeznie compilerOptions.allowSyntheticDefaultImports kell. Vegye figyelembe, hogy ha engedélyeztecompilerOptions.esModuleInteropallowSyntheticDefaultImports, alapértelmezés szerint engedélyezve van. További információt a TypeScript fordítói beállításainak kézikönyvében talál.

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, először egy kötegelőt kell használnia. Ennek részleteiért tekintse meg a csomagküldő dokumentációt.

Az itt leírtakon kívül ez a kódtár további polifillekre is szüksége van a következő NodeJS core beépített modulokhoz, hogy megfelelően működjön a böngészőkben:

• buffer
• os
• path
• process

Bundling with Webpack

Ha a Webpack v5-öt használja, a következő fejlesztői függőségeket telepítheti

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

majd adja hozzá a következőket a 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"),
+    },
   },

Összevonás kumulatív frissítéssel

Kumulatív csomagkezelő használata esetén telepítse a következő fejlesztői függőségeket

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

Ezután adja meg a következőket a 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"],
+    }),
  ]
};

A polifillek használatával kapcsolatos további információkért tekintse meg kedvenc csomagkezelőjének dokumentációját.

React natív támogatás

A böngészőkhöz hasonlóan a React Native nem támogatja az SDK-kódtár által használt JavaScript API-kat, ezért polifilleket kell biztosítania számukra. További részletekért tekintse meg az Messaging React natív mintáját az Expóval .

Az ügyfél hitelesítése

A Service Bus használata a ServiceBusClient osztály egy példányával kezdődik. A Service Busban kapcsolati sztringgel vagy Azure Active Directory-hitelesítő adatok használatával végezhet hitelesítést.

Kapcsolati sztring használata

Ez a metódus a kapcsolati sztringet a Service Bus-példányhoz viszi. A kapcsolati sztringet az Azure Portalról szerezheti be.

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

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

Erről a konstruktorról az API dokumentációjában talál további információt.

Azure Active Directory hitelesítő adatok használata

Az Azure Active Directoryval történő hitelesítés az Azure Identity-kódtárat használja.

Az alábbi példa a DefaultAzureCredential függvényt használja, amely a @azure/identity tárban elérhető számos hitelesítőadat-szolgáltató egyike.

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

MEGJEGYZÉS: Ha a felület saját implementációját használja az TokenCredential AAD-hez, állítsa be a service-bus "hatóköreit" a következőre a megfelelő jogkivonat beszerzéséhez:

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

Erről a konstruktorról további információt az API dokumentációjában talál.

Fő fogalmak

A inicializálást ServiceBusClientkövetően a következő erőforrásokat használhatja egy Service Bus-névtérben:

• Üzenetsorok: Lehetővé teszi az üzenetek küldését és fogadását. Gyakran használják pont–pont kommunikációhoz.
• Témakörök: Az üzenetsorok helyett a témakörök jobban megfelelnek a közzétételi/feliratkozási forgatókönyveknek. Egy témakör elküldhető a címzettnek, de olyan előfizetést igényel, amelyből egyszerre több is lehet.
• Előfizetések: A témakörből felhasználandó mechanizmus. Minden előfizetés független, és megkapja a témakörbe küldött üzenetek másolatát. A szabályok és szűrők segítségével testre szabható, hogy egy adott előfizetés mely üzeneteket fogadja.

További információ ezekről az erőforrásokról: Mi az az Azure Service Bus?.

Ezeknek az erőforrásoknak a használatához ismernie kell a következő SDK-fogalmakat:

• Üzenetek küldése üzenetsorba vagy témakörbe a ServiceBusSender használatával létrehozott paranccsal ServiceBusClient.createSender().
• Üzenetek fogadása egy üzenetsorból vagy egy előfizetésből a ServiceBusReceiver használatával létrehozott paranccsal ServiceBusClient.createReceiver().
• Üzenetek fogadása munkamenet-kompatibilis üzenetsorokból vagy előfizetésekből, a ServiceBusSessionReceiver vagy ServiceBusClient.acceptNextSession()használatával létrehozott paranccsalServiceBusClient.acceptSession().

Vegye figyelembe, hogy a kódtár használata előtt létre kell hozni az üzenetsorokat, a témaköröket és az előfizetéseket.

Példák

Az alábbi szakaszok olyan kódrészleteket nyújtanak, amelyek az Azure Service Bus használatával végzett gyakori feladatok némelyikét ismertetik

• Üzenetek küldése
• Üzenetek fogadása
• Üzenet rendezése
• Kézbesítetlen levelek üzenetsorai
• Üzenetek küldése munkamenetek használatával
• Üzenetek fogadása munkamenetekből
• Service Bus-névtér erőforrásainak kezelése
• További minták

Üzenetek küldése

Miután létrehozott egy osztálypéldányt ServiceBusClient , lekérheti ServiceBusSender a createSender metódust, amellyel üzeneteket küldhet .

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

Üzenetek fogadása

Miután létrehozott egy osztálypéldánytServiceBusClient, a createReceiver metódussal szerezhet be egy ServiceBusReceiver példányt.

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

Két receiveModes érhető el.

• "peekLock" – PeekLock módban a fogadó zárolja az üzenetet az üzenetsoron megadott ideig.
• "receiveAndDelete" – A receiveAndDelete módban az üzenetek a fogadásukkor törlődnek a Service Busból.

Ha a receiveMode nincs megadva a beállítások között, az alapértelmezés szerint a "peekLock" módba kerül. A beérkezett üzeneteket "peekLock" módban is rendezheti .

Ezt a fogadót háromféleképpen használhatja az üzenetek fogadásához:

Üzenetek tömbjének lekérése

Használja a receiveMessages függvényt, amely egy ígéretet ad vissza, amely üzenetek tömbjeként oldható fel.

const myMessages = await receiver.receiveMessages(10);

Feliratkozás üzenetkezelővel

Az előfizetési metódus használatával beállíthatja az üzenetkezelőket, és a szükséges ideig futtathatja azt.

Ha végzett, hívja fel a hívást receiver.close() , hogy ne fogadjon többé üzeneteket.

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

Aszinkron iterátor használata

A getMessageIterator használata az aszinkron iterátor üzeneteken keresztüli lekéréséhez

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

Üzenet rendezése

Miután megkapta az üzenetet, meghívhatja completeMessage()a , abandonMessage()deferMessage() vagy deadLetterMessage() a fogadót attól függően, hogy hogyan szeretné rendezni az üzenetet.

További információ: Fogadott üzenetek rendezése

Kézbesítetlen levelek üzenetsorai

A kézbesítetlen levelek várólistája egy alsor. Minden üzenetsornak vagy előfizetésnek saját kézbesítetlen üzenetsora van. A kézbesítetlen levelek üzenetsorai olyan üzeneteket tárolnak, amelyek kifejezetten kézbesítetlenek (via receiver.deadLetterMessage()), vagy olyan üzeneteket, amelyek túllépték a maximális kézbesítési számukat.

A kézbesítetlen levelek alsorához tartozó fogadó létrehozása hasonló az előfizetéshez vagy üzenetsorhoz tartozó fogadó létrehozásához:

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

A kézbesítetlen levelek üzenetsorait részletesebben szemléltető teljes minták:

• A receiver.deadLetterMessage() használatával explicit módon küldhet üzeneteket a kézbesítetlen levelek alsorába
• Üzenetek fogadása a kézbesítetlen levelek alsorából

Üzenetek küldése munkamenetek használatával

A munkamenetek használatához létre kell hoznia egy munkamenet-kompatibilis üzenetsort vagy előfizetést. A funkció konfigurálásáról a portálon itt olvashat bővebben.

Ha üzeneteket szeretne küldeni egy munkamenetbe, az paranccsal ServiceBusClient hozzon létre egy feladót a createSender használatával.

Az üzenet elküldésekor állítsa be az sessionId üzenet tulajdonságát, hogy az üzenet a megfelelő munkamenetbe kerüljön.

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

A munkamenetek működéséről itt olvashat bővebben.

Üzenetek fogadása munkamenetekből

A munkamenetek használatához létre kell hoznia egy munkamenet-kompatibilis üzenetsort vagy előfizetést. A funkció konfigurálásáról a portálon itt olvashat bővebben.

A nem munkamenet-kompatibilis üzenetsoroktól vagy előfizetésektől eltérően egy munkamenetből bármikor csak egyetlen fogadó olvashat. Ezt egy munkamenet zárolásával kényszeríti ki, amelyet a Service Bus kezel. Elméletileg ez hasonló ahhoz, ahogyan az üzenetzárolás üzemmód használatakor peekLock működik – amikor egy üzenet (vagy munkamenet) zárolva van, a fogadó kizárólagos hozzáféréssel rendelkezik hozzá.

Munkamenet megnyitásához és zárolásához hozzon létre egy SessionReceiver-példánytServiceBusClient.

Kétféleképpen választhatja ki a megnyitni kívánt munkamenetet:

1. Adjon meg egy sessionIdnevű munkamenetet zároló elemet.

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

2. Ne adjon meg munkamenet-azonosítót. Ebben az esetben a Service Bus megkeresi a következő elérhető munkamenetet, amely még nincs zárolva.

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

   A munkamenet nevét a tulajdonságon keresztül sessionId találja meg.SessionReceiver Ha a receiveMode nincs megadva a beállítások között, az alapértelmezés szerint a "peekLock" módba kerül. A beérkezett üzeneteket "peekLock" módban is rendezheti .

A fogadó létrehozása után az üzenetek fogadásának 3 módja közül választhat:

• Üzenetek tömbjének lekérése
• Feliratkozás üzenetkezelővel
• Aszinkron iterátor használata

A munkamenetek működéséről itt olvashat bővebben.

Service Bus-névtér erőforrásainak kezelése

ServiceBusAdministrationClient lehetővé teszi egy névtér kezelését CRUD-műveletekkel az entitásokon (üzenetsorokon, témakörökön és előfizetéseken) és az előfizetések szabályain.

• Támogatja a service bus kapcsolati sztringgel és az AAD hitelesítő adataival való hitelesítést a ServiceBusClientkövetkezőhöz hasonló módon@azure/identity: .

Megjegyzés: A Service Bus még nem támogatja a CORS-szabályok beállítását a névterekhez, ezért ServiceBusAdministrationClient nem működik a böngészőben a webbiztonság letiltása nélkül. További információt itt talál.

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

• Referenciaminta – administrationClient.ts

Hibaelhárítás

Íme néhány kezdeti lépés a problémák diagnosztizálásához. További információt a Service Bus hibaelhárítási útmutatójában talál.

AMQP-függőségek

A Service Bus-kódtár az rhea-promise kódtártól függ, amely kezeli a kapcsolatokat, üzeneteket küld és fogad az AMQP protokollon keresztül.

Naplózás

A kódtár használatakor a következő környezeti változót állíthatja be a hibakeresési naplók lekéréséhez.

• Hibakeresési naplók lekérése a Service Bus SDK-ból

export DEBUG=azure*

• Hibakeresési naplók lekérése a Service Bus SDK-ból és a protokollszintű kódtárból.

export DEBUG=azure*,rhea*

• Ha nem szeretné megtekinteni az üzenetátalakítást (amely sok konzolt/lemezterületet használ), akkor a környezeti változót az DEBUG alábbiak szerint állíthatja be:

export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer

• Ha csak a hibák érdeklik, a környezeti változót a DEBUG következőképpen állíthatja be:

export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Naplózás fájlba

1. A környezeti változó beállítása a DEBUG fent látható módon
2. Futtassa a tesztszkriptet az alábbiak szerint:

• A tesztszkriptből származó naplózási utasítások az out.log sdk-ból a következőre kerülnek debug.log: .

  node your-test-script.js > out.log 2>debug.log
  

• A tesztszkriptből és az sdk-ból származó naplóutasítások ugyanarra a fájlra out.log kerülnek az stderr és az stdout (&1) átirányításával, majd az stdout átirányításával egy fájlba:

  node your-test-script.js >out.log 2>&1
  

• A tesztszkriptből és az sdk-ból származó naplózási utasítások ugyanarra a fájlra out.logkerülnek.

    node your-test-script.js &> out.log
  

Következő lépések

Tekintse meg a mintakönyvtárat , amely részletes példákat tartalmaz arra vonatkozóan, hogyan küldhet és fogadhat üzeneteket a Service Bus-üzenetsorok, -témakörök és -előfizetések között.

Közreműködés

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód összeállításáról és teszteléséről.