Biblioteka klienta usługi Azure Service Bus dla języka JavaScript — wersja 7.9.5

Usługa Azure Service Bus to wysoce niezawodna usługa obsługi komunikatów w chmurze firmy Microsoft.

Używanie biblioteki @azure/service-bus klienta w aplikacji do

• Wysyłanie komunikatów do kolejki lub tematu usługi Azure Service Bus
• Odbieranie komunikatów z kolejki lub subskrypcji usługi Azure Service Bus
• Tworzenie/pobieranie/usuwanie/aktualizowanie/aktualizowanie/wyświetlanie listy kolejek/tematów/subskrypcji/reguł w przestrzeni nazw usługi Azure Service Bus.

Zasoby dla @azure/service-bus wersji 7:

Kluczowe linki:

• Kod źródłowy
• Pakiet (npm)
• Dokumentacja interfejsu API
• Dokumentacja produktu
• Samples
• Przewodnik rozwiązywania problemów

UWAGA: Jeśli używasz wersji 1.1.10 lub nowszej i chcesz przeprowadzić migrację do najnowszej wersji tego pakietu, zapoznaj się z naszym przewodnikiem migracji, aby przejść z usługi Service Bus V1 do usługi Service Bus V7

Wprowadzenie

Instalowanie pakietu

Zainstaluj najnowszą wersję biblioteki klienta usługi Azure Service Bus przy użyciu narzędzia npm.

npm install @azure/service-bus

Obecnie obsługiwane środowiska

• Wersje ltS Node.js

Wymagania wstępne

• Subskrypcja platformy Azure
• Przestrzeń nazw usługi Service Bus

Konfigurowanie języka TypeScript

Użytkownicy języka TypeScript muszą mieć zainstalowane definicje typu węzła:

npm install @types/node

Należy również włączyć compilerOptions.allowSyntheticDefaultImports w tsconfig.json. Pamiętaj, że jeśli włączono compilerOptions.esModuleInteropusługę , allowSyntheticDefaultImports jest domyślnie włączona. Aby uzyskać więcej informacji, zobacz podręcznik dotyczący opcji kompilatora języka TypeScript .

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw musisz użyć pakietu. Aby uzyskać szczegółowe informacje na temat tego, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów.

Oprócz opisanych w tym miejscu elementów ta biblioteka wymaga również dodatkowych poliwypełnień dla następujących wbudowanych modułów nodeJS w celu poprawnego działania w przeglądarkach:

• buffer
• os
• path
• process

Tworzenie pakietów za pomocą pakietu webpack

Jeśli używasz pakietu Webpack w wersji 5, możesz zainstalować następujące zależności deweloperskie

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

następnie dodaj następujące elementy do 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"),
+    },
   },

Łączenie z pakietem zbiorczym

Jeśli używasz pakietu zbiorczego, zainstaluj następujące zależności deweloperskie

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

Następnie uwzględnij następujące elementy w 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"],
+    }),
  ]
};

Aby uzyskać więcej informacji na temat korzystania z technologii polyfill, zapoznaj się z dokumentacją ulubionego pakietu.

Obsługa natywna platformy React

Podobnie jak w przypadku przeglądarek, platforma React Native nie obsługuje niektórych interfejsów API języka JavaScript używanych przez tę bibliotekę zestawu SDK, dlatego należy zapewnić dla nich wielowypełnianie. Aby uzyskać więcej informacji, zobacz przykład React Native z językiem React Native z językiem Expo .

Uwierzytelnianie klienta

Interakcja z usługą Service Bus rozpoczyna się od wystąpienia klasy ServiceBusClient . Możesz uwierzytelnić się w usłudze Service Bus przy użyciu parametrów połączenia lub poświadczeń usługi Azure Active Directory.

Używanie parametrów połączenia

Ta metoda pobiera parametry połączenia do wystąpienia usługi Service Bus. Parametry połączenia można pobrać z witryny Azure Portal.

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

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

Więcej informacji o tym konstruktorze jest dostępnych w dokumentacji interfejsu API.

Używanie poświadczeń usługi Azure Active Directory

Uwierzytelnianie za pomocą usługi Azure Active Directory używa biblioteki azure Identity.

W poniższym przykładzie użyto wartości DefaultAzureCredential, jednego z wielu dostępnych dostawców poświadczeń z biblioteki @azure/identity .

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

UWAGA: Jeśli używasz własnej implementacji interfejsu TokenCredential względem usługi AAD, ustaw "zakresy" dla usługi Service-Bus na następujące, aby uzyskać odpowiedni token:

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

Więcej informacji o tym konstruktorze jest dostępnych w dokumentacji interfejsu API

Kluczowe pojęcia

Po zainicjowaniu ServiceBusClientelementu można wchodzić w interakcje z tymi zasobami w przestrzeni nazw usługi Service Bus:

• Kolejki: umożliwia wysyłanie i odbieranie komunikatów. Często używane do komunikacji punkt-punkt.
• Tematy: W przeciwieństwie do kolejek tematy lepiej nadają się do publikowania/subskrybowania scenariuszy. Temat można wysłać do, ale wymaga subskrypcji, z której może być wiele równoległych, do użycia.
• Subskrypcje: mechanizm korzystania z tematu. Każda subskrypcja jest niezależna i otrzymuje kopię każdego komunikatu wysłanego do tematu. Reguły i filtry mogą służyć do dostosowywania komunikatów odbieranych przez określoną subskrypcję.

Aby uzyskać więcej informacji na temat tych zasobów, zobacz Co to jest usługa Azure Service Bus?.

Aby korzystać z tych zasobów, należy zapoznać się z następującymi pojęciami dotyczącymi zestawu SDK:

• Wysyłanie komunikatów do kolejki lub tematu przy użyciu utworzonego ServiceBusSender przy użyciu polecenia ServiceBusClient.createSender().
• Odbieranie komunikatów z kolejki lub subskrypcji przy użyciu utworzonego ServiceBusReceiver przy użyciu polecenia ServiceBusClient.createReceiver().
• Odbieranie komunikatów z kolejek lub subskrypcji z włączoną sesją ServiceBusSessionReceiver przy użyciu polecenia ServiceBusClient.acceptSession() lub ServiceBusClient.acceptNextSession().

Pamiętaj, że przed użyciem tej biblioteki należy utworzyć kolejki, tematy i subskrypcje.

Przykłady

W poniższych sekcjach przedstawiono fragmenty kodu, które obejmują niektóre typowe zadania przy użyciu usługi Azure Service Bus

• Wysyłanie komunikatów
• Odbieranie komunikatów
• Rozstrzygnąć komunikat
• Kolejki utraconych listów
• Wysyłanie komunikatów przy użyciu sesji
• Odbieranie komunikatów z sesji
• Zarządzanie zasobami przestrzeni nazw usługi Service Bus
• Dodatkowe przykłady

Wysyłanie komunikatów

Po utworzeniu ServiceBusClient wystąpienia klasy możesz uzyskać metodę ServiceBusSendercreateSender , której można użyć do wysyłania komunikatów.

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

Odbieranie komunikatów

Po utworzeniu ServiceBusClient wystąpienia klasy można uzyskać metodę ServiceBusReceivercreateReceiver .

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

Dostępne są dwa receiveModes.

• "peekLock" — w trybie peekLock odbiornik ma blokadę komunikatu przez czas określony w kolejce.
• "receiveAndDelete" — w trybie odbieraniaAndDelete komunikaty są usuwane z usługi Service Bus, gdy są odbierane.

Jeśli tryb receiveMode nie jest podany w opcjach, domyślnie jest to tryb "peekLock". Możesz również rozstrzygnąć komunikaty odebrane w trybie "peekLock".

Tego odbiornika można użyć na jeden z 3 sposobów odbierania komunikatów:

Pobieranie tablicy komunikatów

Użyj funkcji receiveMessages , która zwraca obietnicę rozpoznawaną w tablicy komunikatów.

const myMessages = await receiver.receiveMessages(10);

Subskrybowanie przy użyciu programu obsługi komunikatów

Użyj metody subskrybuj , aby skonfigurować programy obsługi komunikatów i mieć uruchomione tak długo, jak to konieczne.

Po zakończeniu wywołaj metodę receiver.close() , aby zatrzymać odbieranie kolejnych komunikatów.

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

Używanie iteratora asynchronicznego

Używanie polecenia getMessageIterator do pobierania iteratora asynchronicznego za pośrednictwem komunikatów

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

Rozstrzygnąć komunikat

Po otrzymaniu komunikatu możesz wywołać completeMessage()metodę , abandonMessage()deferMessage() lub deadLetterMessage() na odbiorniku w oparciu o sposób rozliczenia komunikatu.

Aby dowiedzieć się więcej, przeczytaj Temat Rozliczenie odebranych komunikatów

Kolejki utraconych listów

Kolejka utraconych wiadomości to kolejka podrzędna. Każda kolejka lub subskrypcja ma własną kolejkę utraconych wiadomości. Kolejki utraconych listów przechowują komunikaty, które zostały jawnie zakleszczone (za pośrednictwem receiver.deadLetterMessage()metody ) lub wiadomości, które przekroczyły maksymalną liczbę dostaw.

Tworzenie odbiornika dla kolejki podrzędnej utraconych wiadomości jest podobne do tworzenia odbiornika dla subskrypcji lub kolejki:

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

Pełne próbki przedstawiające kolejki utraconych listów dokładniej:

• Używanie parametru receiver.deadLetterMessage() do jawnego wysyłania komunikatów do kolejki podrzędnej utraconych wiadomości
• Odbieranie komunikatów z kolejki podrzędnej utraconych wiadomości

Wysyłanie komunikatów przy użyciu sesji

Używanie sesji wymaga utworzenia sesji z włączoną kolejką lub subskrypcją. Więcej informacji na temat konfigurowania tej funkcji można znaleźć w portalu tutaj.

Aby wysyłać komunikaty do sesji, użyj elementu ServiceBusClient , aby utworzyć nadawcę przy użyciu polecenia createSender.

Podczas wysyłania komunikatu ustaw sessionId właściwość w komunikacie, aby upewnić się, że komunikat zostanie wyświetlony w odpowiedniej sesji.

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

Więcej informacji o sposobie działania sesji można znaleźć tutaj.

Odbieranie komunikatów z sesji

Używanie sesji wymaga utworzenia sesji z włączoną kolejką lub subskrypcją. Więcej informacji na temat konfigurowania tej funkcji można znaleźć w portalu tutaj.

W przeciwieństwie do kolejek lub subskrypcji z obsługą sesji tylko jeden odbiornik może odczytywać z sesji w dowolnym momencie. Jest to wymuszane przez zablokowanie sesji obsługiwanej przez usługę Service Bus. Koncepcyjnie jest to podobne do sposobu działania blokowania komunikatów w przypadku korzystania z peekLock trybu — gdy komunikat (lub sesja) jest zablokowany, odbiornik ma wyłączny dostęp do niego.

Aby otworzyć i zablokować sesję, użyj wystąpienia, ServiceBusClient aby utworzyć element SessionReceiver.

Istnieją dwa sposoby wybierania sesji do otwarcia:

1. Określ element sessionId, który blokuje nazwaną sesję.

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

2. Nie należy określać identyfikatora sesji. W takim przypadku usługa Service Bus znajdzie następną dostępną sesję, która nie jest jeszcze zablokowana.

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

   Nazwę sesji można znaleźć za pośrednictwem sessionId właściwości w obiekcie SessionReceiver. Jeśli tryb receiveMode nie jest podany w opcjach, domyślnie jest to tryb "peekLock". Możesz również rozstrzygnąć komunikaty odebrane w trybie "peekLock".

Po utworzeniu odbiornika można użyć między 3 sposobami odbierania komunikatów:

• Pobieranie tablicy komunikatów
• Subskrybowanie przy użyciu programu obsługi komunikatów
• Używanie iteratora asynchronicznego

Więcej informacji o sposobie działania sesji można znaleźć tutaj.

Zarządzanie zasobami przestrzeni nazw usługi Service Bus

ServiceBusAdministrationClient Umożliwia zarządzanie przestrzenią nazw za pomocą operacji CRUD na jednostkach (kolejkach, tematach i subskrypcjach) oraz regułach subskrypcji.

• Obsługuje uwierzytelnianie za pomocą parametrów połączenia usługi Service Bus, a także poświadczenia usługi AAD podobne @azure/identity do ServiceBusClient.

Uwaga: usługa Service Bus nie obsługuje jeszcze ustawiania reguł CORS dla przestrzeni nazw, dlatego ServiceBusAdministrationClient nie będzie działać w przeglądarce bez wyłączania zabezpieczeń sieci Web. Aby uzyskać więcej informacji, zobacz tutaj.

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

• Przykład do dokumentacji — administrationClient.ts

Rozwiązywanie problemów

Poniżej przedstawiono kilka początkowych kroków, aby rozpocząć diagnozowanie problemów. Aby uzyskać więcej informacji, zapoznaj się z przewodnikiem rozwiązywania problemów z usługą Service Bus.

Zależności amQP

Biblioteka usługi Service Bus zależy od biblioteki rhea-promise do zarządzania połączeniami, wysyłania i odbierania komunikatów za pośrednictwem protokołu AMQP .

Rejestrowanie

W przypadku korzystania z tej biblioteki można ustawić następującą zmienną środowiskową, aby pobrać dzienniki debugowania.

• Pobieranie dzienników debugowania z zestawu SDK usługi Service Bus

export DEBUG=azure*

• Pobieranie dzienników debugowania z zestawu SDK usługi Service Bus i biblioteki poziomu protokołu.

export DEBUG=azure*,rhea*

• Jeśli nie interesuje Cię wyświetlanie przekształcenia komunikatu (które zużywa dużo miejsca na dysku/konsoli), możesz ustawić DEBUG zmienną środowiskową w następujący sposób:

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

• Jeśli interesuje Cię tylko błędy, możesz ustawić zmienną DEBUG środowiskową w następujący sposób:

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

Rejestrowanie w pliku

1. Ustaw zmienną DEBUG środowiskową, jak pokazano powyżej
2. Uruchom skrypt testowy w następujący sposób:

• Instrukcje rejestrowania ze skryptu testowego przejdź do out.log instrukcji rejestrowania z zestawu SDK i przejdź do debug.log.

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

• Instrukcje rejestrowania ze skryptu testowego i zestawu SDK przechodzą do tego samego pliku out.log , przekierowując stderr do stdout (&1), a następnie przekierowując stdout do pliku:

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

• Instrukcje rejestrowania ze skryptu testowego i zestawu SDK przejdź do tego samego pliku out.log.

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

Następne kroki

Zapoznaj się z katalogiem przykładów , aby uzyskać szczegółowe przykłady dotyczące używania tej biblioteki do wysyłania i odbierania komunikatów do/z kolejek, tematów i subskrypcji usługi Service Bus.

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat sposobu kompilowania i testowania kodu.