Biblioteca de cliente do Azure Service Bus para JavaScript – versão 7.9.5

O Azure Service Bus é um serviço de mensagens na cloud altamente fiável da Microsoft.

Utilizar a biblioteca @azure/service-bus de cliente na sua aplicação para

• Enviar mensagens para uma Fila ou Tópico do Azure Service Bus
• Receber mensagens de uma Fila ou Subscrição do Azure Service Bus
• Criar/Obter/Eliminar/Atualizar/Listar Filas/Tópicos/Subscrições/Regras num espaço de nomes do Azure Service Bus.

Recursos para a @azure/service-bus versão 7:

Ligações principais:

• Código fonte
• Pacote (npm)
• Documentação de Referência da API
• Documentação do produto
• Amostras
• Guia de Resolução de Problemas

NOTA: se estiver a utilizar a versão 1.1.10 ou inferior e quiser migrar para a versão mais recente deste pacote, veja o nosso guia de migração para mudar do Service Bus V1 para o Service Bus V7

Introdução

Instalar o pacote

Instale a versão mais recente da biblioteca de cliente do Azure Service Bus com o npm.

npm install @azure/service-bus

Ambientes atualmente suportados

• Versões LTS do Node.js

Pré-requisitos

• Uma subscrição do Azure
• Um Espaço de Nomes do Service Bus

Configurar TypeScript

Os utilizadores do TypeScript precisam de ter definições de tipo de Nó instaladas:

npm install @types/node

Também tem de ativar compilerOptions.allowSyntheticDefaultImports no seu tsconfig.json. Tenha em atenção que, se tiver ativado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está ativado por predefinição. Veja o manual de opções do compilador do TypeScript para obter mais informações.

Pacote JavaScript

Para utilizar esta biblioteca de cliente no browser, primeiro tem de utilizar um bundler. Para obter detalhes sobre como fazê-lo, veja a nossa documentação de agrupamento.

Além do que é descrito, esta biblioteca também precisa de polifills adicionais para os seguintes módulos incorporados no nodeJS core para funcionar corretamente nos browsers:

• buffer
• os
• path
• process

Agrupamento com Webpack

Se estiver a utilizar o Webpack v5, pode instalar as seguintes dependências de programador

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

em seguida, adicione o seguinte à sua 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"),
+    },
   },

Agrupamento com Rollup

Se estiver a utilizar o Pacote de rollup, instale as seguintes dependências de programador

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

Em seguida, inclua o seguinte no seu 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"],
+    }),
  ]
};

Consulte a documentação do seu bundler favorito para obter mais informações sobre como utilizar polifills.

Suporte Nativo do React

À semelhança dos browsers, o React Native não suporta alguma api JavaScript utilizada por esta biblioteca do SDK, pelo que tem de fornecer polifills para os mesmos. Veja o exemplo Nativo do Messaging React com a Expo para obter mais detalhes.

Autenticar o cliente

A interação com o Service Bus começa com uma instância da classe ServiceBusClient . Pode autenticar no Service Bus com uma cadeia de ligação ou com uma credencial do Azure Active Directory.

Utilizar uma cadeia de ligação

Este método utiliza a cadeia de ligação para a instância do Service Bus. Pode obter a cadeia de ligação no portal do Azure.

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

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

Estão disponíveis mais informações sobre este construtor na documentação da API.

Utilizar uma Credencial do Azure Active Directory

A autenticação com o Azure Active Directory utiliza a biblioteca de Identidades do Azure.

O exemplo abaixo utiliza DefaultAzureCredential, um dos muitos fornecedores de credenciais disponíveis da @azure/identity biblioteca.

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 estiver a utilizar a sua própria implementação da TokenCredential interface no AAD, defina os "âmbitos" do service-bus para o seguinte para obter o token adequado:

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

Estão disponíveis mais informações sobre este construtor na documentação da API

Conceitos-chave

Depois de inicializar um ServiceBusClient, pode interagir com estes recursos num Espaço de Nomes do Service Bus:

• Filas: permite o envio e a receção de mensagens. Frequentemente utilizado para comunicação ponto a ponto.
• Tópicos: ao contrário das Filas, os Tópicos são mais adequados para publicar/subscrever cenários. Um tópico pode ser enviado para, mas requer uma subscrição, da qual pode haver vários em paralelo, para consumir.
• Subscrições: o mecanismo a consumir a partir de um Tópico. Cada subscrição é independente e recebe uma cópia de cada mensagem enviada para o tópico. As regras e filtros podem ser utilizados para personalizar as mensagens recebidas por uma subscrição específica.

Para obter mais informações sobre estes recursos, veja O que é o Azure Service Bus?.

Para interagir com estes recursos, deve estar familiarizado com os seguintes conceitos do SDK:

• Enviar mensagens, para uma fila ou tópico, através de um ServiceBusSender criado com ServiceBusClient.createSender().
• Receber mensagens, de uma fila ou de uma subscrição, através de uma ServiceBusReceiver criada com ServiceBusClient.createReceiver().
• Receber mensagens, de filas ou subscrições com sessão ativada, através de um ServiceBusSessionReceiver criado com o ServiceBusClient.acceptSession() ou ServiceBusClient.acceptNextSession().

Tenha em atenção que as Filas, Tópicos e Subscrições devem ser criados antes de utilizar esta biblioteca.

Exemplos

As secções seguintes fornecem fragmentos de código que abrangem algumas das tarefas comuns com o Azure Service Bus

• Enviar mensagens
• Receber mensagens
• Resolver uma mensagem
• Filas de mensagens não entregues
• Enviar mensagens com Sessões
• Receber mensagens de Sessões
• Gerir recursos de um espaço de nomes do service bus
• Exemplos adicionais

Enviar mensagens

Depois de criar uma instância de uma ServiceBusClient classe, pode obter uma ServiceBusSender com o método createSender que pode utilizar para enviar mensagens.

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

Receber mensagens

Depois de criar uma instância de uma ServiceBusClient classe, pode obter uma ServiceBusReceiver com o método createReceiver .

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

Existem dois receiveModedisponíveis.

• "peekLock" – no modo peekLock, o recetor tem um bloqueio na mensagem durante a duração especificada na fila.
• "receiveAndDelete" - No modo receiveAndDelete, as mensagens são eliminadas do Service Bus à medida que são recebidas.

Se o receiveMode não for fornecido nas opções, a predefinição é o modo "peekLock". Também pode resolver as mensagens recebidas no modo "peekLock".

Pode utilizar este recetor de uma das três formas de receber mensagens:

Obter uma matriz de mensagens

Utilize a função receiveMessages que devolve uma promessa que é resolvida para uma matriz de mensagens.

const myMessages = await receiver.receiveMessages(10);

Subscrever com um processador de mensagens

Utilize o método de subscrição para configurar processadores de mensagens e executá-lo enquanto precisar.

Quando terminar, ligue receiver.close() para parar de receber mais mensagens.

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

Utilizar iterador assíncrono

Utilizar o getMessageIterator para obter um iterador assíncrono através de mensagens

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

Resolver uma mensagem

Assim que receber uma mensagem, pode chamar completeMessage(), abandonMessage()deferMessage() ou deadLetterMessage() no recetor com base na forma como pretende resolver a mensagem.

Para saber mais, leia Resolver Mensagens Recebidas

Filas de mensagens não entregues

A fila de mensagens não entregues é uma sub-fila. Cada fila ou subscrição tem a sua própria fila de mensagens não entregues. As filas de mensagens não entregues armazenam mensagens explicitamente não entregues (via receiver.deadLetterMessage()) ou mensagens que excederam o número máximo de entregas.

Criar um recetor para uma sub-fila de letras não entregues é semelhante à criação de um recetor para uma subscrição ou fila:

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

Exemplos completos que demonstram filas de mensagens não entregues mais detalhadamente:

• Utilizar receiver.deadLetterMessage() para enviar explicitamente mensagens para a sub-fila de mensagens não entregues
• Receber mensagens da sub-fila de mensagens não entregues

Enviar mensagens com Sessões

A utilização de sessões requer a criação de uma Fila ou Subscrição com sessão ativada. Pode ler mais sobre como configurar esta funcionalidade no portal aqui.

Para enviar mensagens para uma sessão, utilize o ServiceBusClient para criar um remetente com createSender.

Ao enviar a mensagem, defina a sessionId propriedade na mensagem para garantir que a sua mensagem chega à sessão certa.

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

Pode ler mais sobre como as sessões funcionam aqui.

Receber mensagens de Sessões

A utilização de sessões requer a criação de uma Fila ou Subscrição com sessão ativada. Pode ler mais sobre como configurar esta funcionalidade no portal aqui.

Ao contrário das Filas ou Subscrições não ativadas para sessão, apenas um único recetor pode ler a partir de uma sessão em qualquer altura. Isto é imposto ao bloquear uma sessão, que é processada pelo Service Bus. Conceptualmente, isto é semelhante à forma como o bloqueio de mensagens funciona quando utiliza peekLock o modo – quando uma mensagem (ou sessão) está bloqueada, o recetor tem acesso exclusivo ao mesmo.

Para abrir e bloquear uma sessão, utilize uma instância de ServiceBusClient para criar um SessionReceiver.

Existem duas formas de escolher a sessão a abrir:

1. Especifique um sessionId, que bloqueia uma sessão com nome.

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

2. Não especifique um ID de sessão. Neste caso, o Service Bus irá encontrar a próxima sessão disponível que ainda não está bloqueada.

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

   Pode encontrar o nome da sessão através da sessionId propriedade em SessionReceiver. Se o receiveMode não for fornecido nas opções, a predefinição é o modo "peekLock". Também pode resolver as mensagens recebidas no modo "peekLock".

Assim que o recetor for criado, pode utilizar a opção escolher entre 3 formas de receber mensagens:

• Obter uma matriz de mensagens
• Subscrever com um processador de mensagens
• Utilizar iterador assíncrono

Pode ler mais sobre como as sessões funcionam aqui.

Gerir recursos de um espaço de nomes do service bus

ServiceBusAdministrationClient permite-lhe gerir um espaço de nomes com operações CRUD nas entidades (filas, tópicos e subscrições) e nas regras de uma subscrição.

• Suporta a autenticação com uma cadeia de ligação do service bus, bem como com as credenciais do AAD de @azure/identity semelhantes às do ServiceBusClient.

Nota: o Service Bus ainda não suporta a definição de regras CORS para espaços de nomes, pelo ServiceBusAdministrationClient que não funcionará no browser sem desativar a segurança da Web. Para obter mais informações, consulte aqui.

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

• Exemplo de referência - administrationClient.ts

Resolução de problemas

Eis alguns passos iniciais para começar a diagnosticar problemas. Para obter mais informações, veja o Guia de Resolução de Problemas do Service Bus.

Dependências AMQP

A biblioteca do Service Bus depende da biblioteca rhea-promise para gerir ligações, enviar e receber mensagens através do protocolo AMQP .

Registo

Pode definir a seguinte variável de ambiente para obter os registos de depuração ao utilizar esta biblioteca.

• Obter registos de depuração do SDK do Service Bus

export DEBUG=azure*

• Obter registos de depuração do SDK do Service Bus e da biblioteca de nível de protocolo.

export DEBUG=azure*,rhea*

• Se não estiver interessado em ver a transformação de mensagens (que consome muito espaço na consola/disco), pode definir a variável de ambiente da DEBUG seguinte forma:

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

• Se estiver interessado apenas em erros, pode definir a variável de ambiente da DEBUG seguinte forma:

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

Iniciar sessão num ficheiro

1. Defina a variável de DEBUG ambiente conforme mostrado acima
2. Execute o script de teste da seguinte forma:

• As instruções de registo do script de teste vão para out.log e as instruções de registo do sdk vão para debug.log.

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

• As instruções de registo do script de teste e do sdk vão para o mesmo ficheiro out.log ao redirecionar o stderr para stdout (&1) e, em seguida, redirecionar stdout para um ficheiro:

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

• As instruções de registo do script de teste e do sdk vão para o mesmo ficheiro out.log.

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

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca para enviar e receber mensagens de/para Filas, Tópicos e Subscrições do Service Bus.

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.