Condividi tramite

Libreria client del bus di servizio di Azure per JavaScript - versione 7.9.5

  • Articolo

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

Usare 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 una sottoscrizione del bus di servizio di Azure
  • Creare/Get/Delete/Update/List Queues/Topics/Subscriptions/Rules in uno spazio dei nomi del bus di servizio di Azure.

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

Collegamenti principali:

NOTA: se si usa la versione 1.1.10 o versione 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

Introduzione

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

Prerequisiti

Configurare TypeScript

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

npm install @types/node

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

JavaScript Bundle

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, questa libreria necessita anche di polifill aggiuntivi 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 quanto segue 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 nella 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 di React

Analogamente ai browser, React Native non supporta alcune API JavaScript usate da questa libreria SDK, quindi è necessario fornire polifill per tali API. Per altri dettagli, vedere l'esempio React Native 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 nel bus di servizio usando una stringa di connessione o usando le credenziali di Azure Active Directory.

Uso di una stringa di connessione

Questo metodo accetta la stringa di connessione all'istanza del bus di servizio. È possibile ottenere la stringa di connessione nel portale di Azure.

const { ServiceBusClient } = require("@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.

L'esempio seguente usa DefaultAzureCredential, uno dei molti provider di credenziali disponibili dalla @azure/identity libreria.

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

NOTA: se si usa la propria implementazione dell'interfaccia TokenCredential in 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 ServiceBusClientoggetto , è 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 usato per la comunicazione da punto a 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ù in parallelo, da 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 usati 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 concetti dell'SDK seguenti:

Si noti che le code, gli argomenti e le sottoscrizioni devono essere create prima di usare questa libreria.

Esempio

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

Inviare messaggi

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

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 oggetto usando il metodo createReceiver .

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

Sono disponibili due receiveMode.

  • "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 quando vengono ricevuti.

Se receiveMode non viene fornito nelle opzioni, per impostazione predefinita viene impostata la modalità "peekLock". È anche possibile risolvere i messaggi ricevuti in modalità "peekLock".

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

Ottenere una matrice di messaggi

Usare la funzione receiveMessages che restituisce una promessa che viene risolta in una matrice di messaggi.

const myMessages = await receiver.receiveMessages(10);

Sottoscrivere usando un gestore di messaggi

Usare il metodo subscribe per configurare i gestori di messaggi e renderlo in esecuzione, purché sia necessario.

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

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

Usare getMessageIterator per ottenere un iteratore asincrono sui messaggi

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

Risolvere un messaggio

Dopo aver ricevuto un messaggio, è possibile chiamare completeMessage(), deferMessage()abandonMessage()o deadLetterMessage() sul ricevitore in base alla modalità di liquidazione del messaggio.

Per altre informazioni, leggere Settling Received Messages

Code di lettere non recapitabili

La coda di lettere non recapitabili è una coda secondaria. Ogni coda o sottoscrizione ha una coda di lettere non recapitabili. Le code di lettere non recapitabili archiviano messaggi che sono stati recapitati in modo esplicito (tramite receiver.deadLetterMessage()) o messaggi che hanno superato il numero massimo di recapito.

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

// 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 code di lettere non recapitabili più accuratamente:

Inviare messaggi usando sessioni

L'uso delle sessioni richiede di creare una coda o una sottoscrizione abilitata per la sessione. Per altre informazioni su come configurare questa funzionalità nel portale , vedere qui.

Per inviare messaggi a una sessione, usare per ServiceBusClient creare un mittente usando createSender.

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

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

Per altre informazioni sul funzionamento delle sessioni , vedere qui.

Ricevere messaggi dalle sessioni

L'uso delle sessioni richiede di creare una coda o una sottoscrizione abilitata per la sessione. Per altre informazioni su come configurare questa funzionalità nel portale , vedere 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, gestita dal bus di servizio. Concettualmente, questo è simile al funzionamento del blocco dei messaggi quando si usa peekLock la modalità : quando un messaggio (o una sessione) è bloccato il ricevitore ha accesso esclusivo a esso.

Per aprire e bloccare una sessione, usare un'istanza di ServiceBusClient per creare una SessioneReceiver.

Esistono due modi per scegliere quale sessione aprire:

  1. Specificare un oggetto , che blocca una sessionIdsessione 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 sessione disponibile successiva 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 l'oggetto receiveMode non viene fornito nelle opzioni, viene predefinito la modalità "peekLock". È anche possibile stabilire i messaggi ricevuti in modalità "peekLock".

Dopo aver creato il ricevitore, è possibile scegliere tra 3 modi per ricevere i messaggi:

Per altre informazioni sul funzionamento delle sessioni , vedere qui.

Gestire le risorse di uno spazio dei nomi del bus di servizio

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 AAD simili @azure/identity 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 altre informazioni, vedere qui.

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

Risoluzione dei problemi

Ecco alcuni passaggi iniziali per iniziare a diagnosticare i problemi. Per altre informazioni, vedere la Guida alla risoluzione dei problemi del 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 .

Registrazione

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

  • Recupero dei log di debug da Service Bus SDK
export DEBUG=azure*
  • Recupero dei log di debug dall'SDK del bus di servizio e dalla libreria a livello di protocollo.
export DEBUG=azure*,rhea*
  • Se non si è interessati a visualizzare la trasformazione del messaggio (che utilizza un sacco di spazio console/disco), è possibile impostare la DEBUG variabile di ambiente come indicato di seguito:
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • Se si è interessati solo agli errori, è possibile impostare la DEBUG variabile di ambiente come indicato di seguito:
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. Impostare la DEBUG variabile di ambiente come illustrato in precedenza
  2. Eseguire lo script di test come indicato di seguito:
  • Le istruzioni di registrazione dallo script di test passano a out.log e registrano le istruzioni 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

Esaminare la directory degli esempi per esempi dettagliati su come usare questa libreria per inviare e ricevere messaggi da/da code del bus di servizio, argomenti e sottoscrizioni.

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.

Impression