bus di servizio di Azure client library for JavaScript - versione 7.10.0

Il bus di servizio di Azure è un servizio di messaggistica cloud altamente affidabile di Microsoft.

Utilizzare la libreria @azure/service-bus client nell'applicazione per

  • Inviare messaggi a una coda o a un argomento del bus di servizio di Azure
  • Ricevere messaggi da una coda o da una sottoscrizione del bus di servizio di Azure
  • Creare/Ottenere/Eliminare/Aggiornare/Elencare code/argomenti/sottoscrizioni/regole in uno spazio dei nomi del bus di servizio di Azure.

Risorse per @azure/service-bus la versione 7:

Collegamenti chiave:

NOTA: se si usa la versione 1.1.10 o precedente e si vuole eseguire la migrazione alla versione più recente di questo pacchetto, vedere la guida alla migrazione per passare dal bus di servizio V1 al bus di servizio V7

Come iniziare

Installare il pacchetto

Installare la versione più recente per la libreria client del bus di servizio di Azure usando npm.

npm install @azure/service-bus

Ambienti attualmente supportati

Prerequisites

Configurare TypeScript

Gli utenti typeScript devono avere installate definizioni dei tipi di nodo:

npm install @types/node

È anche necessario abilitare compilerOptions.allowSyntheticDefaultImports nel tsconfig.json. Si noti che se è stato abilitato compilerOptions.esModuleInterop, allowSyntheticDefaultImports è abilitato per impostazione predefinita. Per altre informazioni, vedere manuale delle opzioni del compilatore di TypeScript di .

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

Oltre a quanto descritto in questa libreria, questa libreria richiede anche ulteriori polyfill per i moduli predefiniti nodeJS seguenti per funzionare correttamente nei browser:

  • buffer
  • os
  • path
  • process

Creazione di bundle con Webpack

Se si usa Webpack v5, è possibile installare le dipendenze di sviluppo seguenti

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

aggiungere quindi il codice seguente nel 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"),
+    },
   },

Creazione di bundle con rollup

Se si usa Rollup bundler, installare le dipendenze di sviluppo seguenti

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

Includere quindi quanto segue nel 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"],
+    }),
  ]
};

Per altre informazioni sull'uso di polyfill, consultare la documentazione del bundler preferito.

Supporto nativo React

Simile ai browser, React Native non supporta alcune API JavaScript utilizzate da questa libreria SDK, quindi è necessario fornire polyfill per loro. Per altre informazioni, vedere l'esempio react nativo di messaggistica con Expo.

Autenticare il client

L'interazione con il bus di servizio inizia con un'istanza della classe ServiceBusClient . È possibile eseguire l'autenticazione al bus di servizio usando una stringa di connessione o una credenziale di Azure Active Directory.

Uso di una stringa di connessione

Questo metodo accetta la stringa di connessione nell'istanza di bus di servizio. È possibile ottenere la stringa di connessione dal portale di Azure.

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

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

Altre informazioni su questo costruttore sono disponibili nella documentazione dell'API.

Uso di credenziali di Azure Active Directory

L'autenticazione con Azure Active Directory usa la libreria di identità di Azure.

Nell'esempio seguente viene usato DefaultAzureCredential, uno dei numerosi provider di credenziali disponibili nella @azure/identity libreria.

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

NOTA: se si usa un'implementazione personalizzata dell'interfaccia TokenCredential con AAD, impostare gli "ambiti" per il bus di servizio su quanto segue per ottenere il token appropriato:

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

Altre informazioni su questo costruttore sono disponibili nella documentazione dell'API

Concetti chiave

Dopo aver inizializzato un ServiceBusClient, è possibile interagire con queste risorse all'interno di uno spazio dei nomi del bus di servizio:

  • Code: consente l'invio e la ricezione di messaggi. Spesso utilizzato per la comunicazione punto-punto.
  • Argomenti: a differenza delle code, gli argomenti sono più adatti per gli scenari di pubblicazione/sottoscrizione. Un argomento può essere inviato a, ma richiede una sottoscrizione, di cui possono essere presenti più sottoscrizioni in parallelo, da cui utilizzare.
  • Sottoscrizioni: meccanismo da utilizzare da un argomento. Ogni sottoscrizione è indipendente e riceve una copia di ogni messaggio inviato all'argomento. Le regole e i filtri possono essere utilizzati per personalizzare i messaggi ricevuti da una sottoscrizione specifica.

Per altre informazioni su queste risorse, vedere Che cos'è il bus di servizio di Azure?.

Per interagire con queste risorse, è necessario avere familiarità con i seguenti concetti SDK:

Si prega di notare che le code, gli argomenti e gli abbonamenti devono essere creati prima di utilizzare questa libreria.

Examples

Le sezioni seguenti forniscono frammenti di codice che illustrano alcune delle attività comuni con il bus di servizio di Azure

Inviare messaggi

Dopo aver creato un'istanza di una ServiceBusClient classe, è possibile ottenere un ServiceBusSender utilizzando il metodo createSender che è possibile utilizzare per inviare messaggi.

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

Ricevere messaggi

Dopo aver creato un'istanza di una ServiceBusClient classe, è possibile ottenere un ServiceBusReceiver utilizzando il metodo createReceiver .

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

Ci sono due receiveModes disponibili.

  • "peekLock": in modalità peekLock, il ricevitore ha un blocco sul messaggio per la durata specificata nella coda.
  • "receiveAndDelete": in modalità receiveAndDelete, i messaggi vengono eliminati dal bus di servizio non appena vengono ricevuti.

Se receiveMode non è fornito nelle opzioni, per impostazione predefinita viene utilizzata la modalità "peekLock". È inoltre possibile liquidare i messaggi ricevuti in modalità "peekLock".

È possibile utilizzare questo ricevitore in uno dei 3 modi per ricevere messaggi:

Ricevere una matrice di messaggi

Utilizzare la funzione receiveMessages che restituisce una promessa che si risolve in una matrice di messaggi.

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

Sottoscrivere utilizzando un gestore di messaggi

Utilizzare il metodo subscribe per configurare i gestori dei messaggi e farlo funzionare per tutto il tempo necessario.

Al termine, chiama receiver.close() per interrompere la ricezione di altri messaggi.

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

Usare l'iteratore asincrono

Utilizzare getMessageIterator per ottenere un iteratore asincrono sui messaggi

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
}

Liquidare un messaggio

Una volta ricevuto un messaggio, è possibile chiamare completeMessage(), abandonMessage(), deferMessage() o deadLetterMessage() sul ricevitore in base a come si desidera risolvere il messaggio.

Per saperne di più, leggi Liquidazione dei messaggi ricevuti

Code dei messaggi non consegnati

La coda dei messaggi non recapitabili è una coda secondaria. Ogni coda o sottoscrizione dispone di una propria coda di messaggi non recapitabili. Le code di messaggi non recapitabili archiviano i messaggi che sono stati esplicitamente messaggi non recapitabili (tramite receiver.deadLetterMessage()) o i messaggi che hanno superato il numero massimo di recapiti.

La creazione di un ricevitore per una coda secondaria di messaggi non recapitabili è simile alla creazione di un ricevitore per una sottoscrizione o una coda:

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

Esempi completi che illustrano le code di messaggi non recapitabili in modo più approfondito:

Inviare messaggi utilizzando le sessioni

L'utilizzo delle sessioni richiede la creazione di una coda o di una sottoscrizione abilitata per la sessione. Per altre informazioni su come configurare questa funzione, vedere il portale qui.

Per inviare messaggi a una sessione, utilizzare per ServiceBusClient creare un mittente utilizzando createSender.

Quando si invia il messaggio, impostare la sessionId proprietà nel messaggio per assicurarsi che il messaggio arrivi nella sessione corretta.

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

Per saperne di più su come funzionano le sessioni, clicca qui.

Ricevere messaggi dalle sessioni

L'utilizzo delle sessioni richiede la creazione di una coda o di una sottoscrizione abilitata per la sessione. Per altre informazioni su come configurare questa funzione, vedere il portale qui.

A differenza delle code o delle sottoscrizioni non abilitate per la sessione, solo un singolo ricevitore può leggere da una sessione in qualsiasi momento. Questa operazione viene applicata bloccando una sessione, che viene gestita dal bus di servizio. Concettualmente, questo è simile a come funziona il blocco dei messaggi quando si utilizza peekLock la modalità: quando un messaggio (o una sessione) è bloccato, il destinatario ha accesso esclusivo ad esso.

Per aprire e bloccare una sessione, utilizzare un'istanza di ServiceBusClient per creare un oggetto SessionReceiver.

Ci sono due modi per scegliere quale sessione aprire:

  1. Specificare un valore , sessionIdche blocca una sessione denominata.

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

  2. Non specificare un ID sessione. In questo caso, il bus di servizio troverà la successiva sessione disponibile che non è già bloccata.

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

    È possibile trovare il nome della sessione tramite la sessionId proprietà in SessionReceiver. Se receiveMode non è fornito nelle opzioni, per impostazione predefinita viene utilizzata la modalità "peekLock". È inoltre possibile liquidare i messaggi ricevuti in modalità "peekLock".

Una volta creato il ricevitore, è possibile scegliere tra 3 modi per ricevere i messaggi:

Per saperne di più su come funzionano le sessioni, clicca qui.

Elenco delle sessioni di messaggi

Per scoprire quali sessioni hanno messaggi attivi o stato di sessione in una coda o in un abbonamento, usa 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);
}

Gestire le risorse di uno spazio dei nomi di Service Bus

ServiceBusAdministrationClient consente di gestire uno spazio dei nomi con operazioni CRUD sulle entità (code, argomenti e sottoscrizioni) e sulle regole di una sottoscrizione.

  • Supporta l'autenticazione con una stringa di connessione del bus di servizio e con le credenziali @azure/identity AAD di un modello simile a ServiceBusClient.

Nota: il bus di servizio non supporta ancora l'impostazione delle regole CORS per gli spazi dei nomi, quindi ServiceBusAdministrationClient non funzionerà nel browser senza disabilitare la sicurezza Web. Per maggiori informazioni, fai riferimento qui.

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

Di seguito sono riportati alcuni passaggi iniziali per iniziare a diagnosticare i problemi. Per altre informazioni, vedere la Guida alla risoluzione dei problemi di bus di servizio.

Dipendenze AMQP

La libreria del bus di servizio dipende dalla libreria rhea-promise per la gestione delle connessioni, l'invio e la ricezione di messaggi tramite il protocollo AMQP .

Logging

È possibile impostare la variabile di ambiente seguente per ottenere i log di debug quando si usa questa libreria.

  • Recupero dei log di debug da bus di servizio SDK
export DEBUG=azure*
  • Recupero dei log di debug da bus di servizio SDK e dalla libreria a livello di protocollo.
export DEBUG=azure*,rhea*
  • Se non si è interessati a visualizzare la trasformazione del messaggio (che consuma molto spazio su console/disco), è possibile impostare la DEBUG variabile di ambiente come segue:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Se si è interessati solo agli errori, è possibile impostare la variabile d'ambiente DEBUG come segue:
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Registrazione in un file

  1. Imposta la variabile d'ambiente DEBUG come mostrato sopra
  2. Eseguire lo script di test come indicato di seguito:
  • Le istruzioni di registrazione dallo script di test passano a out.log e alle istruzioni di registrazione dall'SDK passano a debug.log. 
    node your-test-script.js > out.log 2>debug.log
  • Le istruzioni di registrazione dallo script di test e l'SDK passano allo stesso file out.log reindirizzando stderr a stdout (&1) e quindi reindirizzare stdout a un file: 
    node your-test-script.js >out.log 2>&1
  • Le istruzioni di registrazione dallo script di test e l'SDK passano allo stesso file out.log. 
      node your-test-script.js &> out.log

Passaggi successivi

Per esempi dettagliati su come usare questa libreria per inviare e ricevere messaggi da/verso code, argomenti e sottoscrizioni del bus di servizio.

Contributing

Se desideri contribuire a questa libreria, leggi la guida contributi per saperne di più su come costruire e testare il codice.

  • Ultimo aggiornamento: