JavaScript için Azure Service Bus istemci kitaplığı - sürüm 7.9.5

Azure Service Bus , Microsoft'un son derece güvenilir bir bulut mesajlaşma hizmetidir.

Uygulamanızdaki istemci kitaplığını @azure/service-bus kullanarak

• Azure Service Bus Kuyruğuna veya Konusuna ileti gönderme
• Azure Service Bus Kuyruğundan veya Aboneliğinden ileti alma
• Azure Service Bus ad alanında Oluşturma/Alma/Silme/Güncelleştirme/Liste Kuyrukları/Konular/Abonelikler/Kurallar.

Sürüm 7 için @azure/service-bus kaynaklar:

Önemli bağlantılar:

• Kaynak kodu
• Paket (npm)
• API Başvuru Belgeleri
• Ürün belgeleri
• Örnekler
• Sorun Giderme Kılavuzu

NOT: Sürüm 1.1.10 veya üzerini kullanıyorsanız ve bu paketin en son sürümüne geçmek istiyorsanız, lütfen Service Bus V1'den Service Bus V7'ye geçiş kılavuzumuza bakın

Başlarken

Paketi yükleme

npm kullanarak Azure Service Bus istemci kitaplığı için en son sürümü yükleyin.

npm install @azure/service-bus

Şu anda desteklenen ortamlar

• Node.jsLTS sürümleri

Önkoşullar

• Azure aboneliği
• Service Bus Ad Alanı

TypeScript'i yapılandırma

TypeScript kullanıcılarının Düğüm türü tanımlarının yüklü olması gerekir:

npm install @types/node

ayrıca tsconfig.json etkinleştirmeniz compilerOptions.allowSyntheticDefaultImports gerekir. seçeneğini etkinleştirdiyseniz compilerOptions.esModuleInteropvarsayılan allowSyntheticDefaultImports olarak etkin olduğunu unutmayın. Daha fazla bilgi için bkz. TypeScript'in derleyici seçenekleri el kitabı .

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için önce bir paketleyici kullanmanız gerekir. Bunun nasıl yapılacağının ayrıntıları için lütfen paketleme belgelerimize bakın.

Burada açıklananlara ek olarak, bu kitaplığın tarayıcılarda düzgün çalışabilmesi için aşağıdaki NodeJS çekirdek yerleşik modülleri için ek polifill'lere de ihtiyacı vardır:

• buffer
• os
• path
• process

Webpack ile Paketleme

Webpack v5 kullanıyorsanız aşağıdaki geliştirme bağımlılıklarını yükleyebilirsiniz

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

ardından aşağıdakileri 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"),
+    },
   },

Toplama ile Paketleme

Rollup bundler kullanıyorsanız aşağıdaki geliştirme bağımlılıklarını yükleyin

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

Ardından aşağıdakileri 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"],
+    }),
  ]
};

Polifill kullanma hakkında daha fazla bilgi için lütfen sık kullandığınız paketleyicinin belgelerine bakın.

React Yerel Desteği

Tarayıcılara benzer şekilde React Native, bu SDK kitaplığı tarafından kullanılan bazı JavaScript api'lerini desteklemediğinden, bunlar için polifill sağlamanız gerekir. Daha fazla ayrıntı için lütfen Expo ile Mesajlaşma React Native örneğine bakın.

İstemcinin kimliğini doğrulama

Service Bus ile etkileşim, ServiceBusClient sınıfının bir örneğiyle başlar. Bağlantı dizesini veya Azure Active Directory kimlik bilgilerini kullanarak Service Bus'ta kimlik doğrulaması yapabilirsiniz.

Bağlantı dizesi kullanma

Bu yöntem bağlantı dizesini Service Bus örneğine götürür. Bağlantı dizesini Azure portalından alabilirsiniz.

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

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

Bu oluşturucu hakkında daha fazla bilgiyi API belgelerinde bulabilirsiniz.

Azure Active Directory Kimlik Bilgilerini Kullanma

Azure Active Directory ile kimlik doğrulaması , Azure Kimlik kitaplığını kullanır.

Aşağıdaki örnekte, kitaplıktan @azure/identity birçok kullanılabilir kimlik bilgisi sağlayıcısından biri olan DefaultAzureCredential kullanılmıştır.

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

NOT: AAD'ye karşı kendi arabirimi uygulamanızı TokenCredential kullanıyorsanız uygun belirteci almak için service-bus için "kapsamları" aşağıdakine ayarlayın:

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

Bu oluşturucu hakkında daha fazla bilgiyi API belgelerinde bulabilirsiniz

Önemli kavramlar

bir ServiceBusClient'i başlatdıktan sonra, Service Bus Ad Alanı içindeki bu kaynaklarla etkileşim kurabilirsiniz:

• Kuyruklar: İleti göndermeye ve almaya izin verir. Genellikle noktadan noktaya iletişim için kullanılır.
• Konular: Kuyrukların aksine, Konular yayımlama/abone olma senaryolarına daha uygundur. Bir konu adresine gönderilebilir, ancak birden çok tane paralel olarak kullanılabilmesi için bir abonelik gerektirir.
• Abonelikler: Bir Konudan tüketecek mekanizma. Her abonelik bağımsızdır ve konuya gönderilen her iletinin bir kopyasını alır. Kurallar ve Filtreler, belirli bir abonelik tarafından alınan iletileri uyarlamak için kullanılabilir.

Bu kaynaklar hakkında daha fazla bilgi için bkz. Azure Service Bus nedir?.

Bu kaynaklarla etkileşime geçmek için aşağıdaki SDK kavramları hakkında bilgi sahibi olmanız gerekir:

• kullanılarak ServiceBusClient.createSender()oluşturulan bir kullanarak ServiceBusSender bir kuyruğa veya konuya ileti gönderin.
• kullanılarak ServiceBusClient.createReceiver()oluşturulan bir kullanarak ServiceBusReceiver kuyruktan veya abonelikten iletiler alın.
• veya ServiceBusClient.acceptNextSession()kullanılarak ServiceBusClient.acceptSession() oluşturulan bir ServiceBusSessionReceiver kullanarak oturum etkinleştirilmiş kuyruklardan veya aboneliklerden iletiler alın.

Bu kitaplığı kullanmadan önce Kuyruklar, Konular ve Abonelikler oluşturulmalıdır.

Örnekler

Aşağıdaki bölümlerde Azure Service Bus kullanan bazı yaygın görevleri kapsayan kod parçacıkları sağlanır

• İleti gönderme
• İleti alma
• İletiyi kapatma
• Teslim edilemeyen ileti kuyrukları
• Oturumları kullanarak ileti gönderme
• Oturumlardan ileti alma
• Service Bus ad alanının kaynaklarını yönetme
• Ek örnekler

İleti gönderme

Bir sınıfın örneğini ServiceBusClient oluşturduktan sonra, ileti göndermek için kullanabileceğiniz createSender yöntemini kullanarak bir alabilirsinizServiceBusSender.

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

İleti alma

Bir sınıfın örneğini ServiceBusClient oluşturduktan sonra createReceiver yöntemini kullanarak bir ServiceBusReceiver alabilirsiniz.

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

İki receiveModetane kullanılabilir.

• "peekLock" - PeekLock modunda, alıcının kuyrukta belirtilen süre boyunca iletide bir kilidi vardır.
• "receiveAndDelete" - receiveAndDelete modunda iletiler alındıklarında Service Bus'tan silinir.

seçeneklerde receiveMode sağlanmadıysa, varsayılan olarak "peekLock" moduna geçer. "PeekLock" modunda alınan iletileri de kapatabilirsiniz .

İleti almak için bu alıcıyı 3 yoldan biriyle kullanabilirsiniz:

İleti dizisi alma

İleti dizisine çözümlenen bir söz döndüren receiveMessages işlevini kullanın.

const myMessages = await receiver.receiveMessages(10);

İleti işleyici kullanarak abone olma

İleti işleyicilerini ayarlamak ve ihtiyacınız olduğu sürece çalışmasını sağlamak için abone olma yöntemini kullanın.

İşiniz bittiğinde, daha fazla ileti almayı durdurmak için arayın receiver.close() .

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

Zaman uyumsuz yineleyici kullanma

İletiler üzerinde zaman uyumsuz bir yineleyici almak için getMessageIterator'ı kullanma

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

İletiyi kapatma

Bir ileti aldıktan sonra, iletiyi nasıl düzeltmek istediğinize bağlı olarak alıcı üzerinde , abandonMessage()deferMessage() veya deadLetterMessage() çağırabilirsinizcompleteMessage().

Daha fazla bilgi edinmek için lütfen Alınan İletileri Kapatma'yı okuyun

Teslim edilemeyen ileti kuyrukları

Teslim edilemeyen ileti kuyruğu bir alt kuyruk. Her kuyruğun veya aboneliğin kendi teslim edilemeyen ileti kuyruğu vardır. Teslim edilemeyen ileti kuyrukları, açıkça teslim edilemeyen iletileri (aracılığıyla receiver.deadLetterMessage()) veya teslim sayısı üst sınırını aşan iletileri depolar.

Teslim edilemeyen bir alt kuyruk için alıcı oluşturmak, abonelik veya kuyruk için alıcı oluşturmaya benzer:

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

Teslim edilemeyen ileti kuyruklarını daha kapsamlı bir şekilde gösteren tam örnekler:

• Teslim edilemeyen ileti alt kuyruğuna açıkça ileti göndermek için receiver.deadLetterMessage() kullanma
• Teslim edilemeyen ileti alt kuyruğundan ileti alma

Oturumları kullanarak ileti gönderme

Oturumları kullanmak için oturum etkin bir Kuyruk veya Abonelik oluşturmanız gerekir. Bu özelliği yapılandırma hakkında daha fazla bilgiyi buradan portalda bulabilirsiniz.

Oturuma ileti göndermek için createSender kullanarak bir gönderen oluşturmak için öğesini kullanınServiceBusClient.

İletiyi gönderirken, iletinizin doğru oturuma geldiğinden emin olmak için iletideki özelliğini ayarlayın sessionId .

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

Oturumların nasıl çalıştığı hakkında daha fazla bilgiyi burada okuyabilirsiniz.

Oturumlardan ileti alma

Oturumları kullanmak için oturum etkin bir Kuyruk veya Abonelik oluşturmanız gerekir. Bu özelliği yapılandırma hakkında daha fazla bilgiyi buradan portalda bulabilirsiniz.

Oturum etkin olmayan Kuyruklardan veya Aboneliklerden farklı olarak, bir oturumdan herhangi bir anda yalnızca tek bir alıcı okuyabilir. Bu, Service Bus tarafından işlenen bir oturumu kilitleyerek uygulanır. Kavramsal olarak, bu mod kullanılırken peekLock ileti kilitlemenin çalışma şekline benzer; bir ileti (veya oturum) kilitlendiğinde alıcınız buna özel erişime sahiptir.

Oturumu açmak ve kilitlemek için bir sessionReceiver oluşturmak için örneğini ServiceBusClient kullanın.

Hangi oturumun aç olacağını seçmenin iki yolu vardır:

1. Adlandırılmış oturumu sessionIdkilitleyen bir belirtin.

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

2. Oturum kimliği belirtmeyin. Bu durumda Service Bus, henüz kilitli olmayan bir sonraki kullanılabilir oturumu bulur.

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

   Oturum adını üzerindeki özelliği SessionReceiveraracılığıyla sessionId bulabilirsiniz. seçeneklerde receiveMode sağlanmadıysa, varsayılan olarak "peekLock" moduna geçer. "PeekLock" modunda alınan iletileri de kapatabilirsiniz .

Alıcı oluşturulduktan sonra iletileri almak için 3 yöntemden birini seçebilirsiniz:

• İleti dizisi alma
• İleti işleyici kullanarak abone olma
• Zaman uyumsuz yineleyici kullanma

Oturumların nasıl çalıştığı hakkında daha fazla bilgiyi burada okuyabilirsiniz.

Service Bus ad alanının kaynaklarını yönetme

ServiceBusAdministrationClient varlıklarda (kuyruklar, konular ve abonelikler) ve bir aboneliğin kurallarında CRUD işlemleriyle ad alanını yönetmenize olanak tanır.

• Service Bus bağlantı dizesiyle ve ile benzer şekilde AAD kimlik bilgileriyle @azure/identity kimlik doğrulamasını ServiceBusClientdestekler.

Not: Service Bus henüz ad alanları için CORS kurallarını ayarlamayı desteklemediğinden, ServiceBusAdministrationClient web güvenliğini devre dışı bırakmadan tarayıcıda çalışmaz. Daha fazla bilgi için buraya bakın.

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

• Başvuru örneği - administrationClient.ts

Sorun giderme

Sorunları tanılamaya başlamak için bazı başlangıç adımları aşağıdadır. Daha fazla bilgi için lütfen Service Bus Sorun Giderme Kılavuzu'na bakın.

AMQP Bağımlılıkları

Service Bus kitaplığı bağlantıları yönetmek, AMQP protokolü üzerinden ileti göndermek ve almak için rhea-promise kitaplığına bağlıdır.

Günlüğe Kaydetme

Bu kitaplığı kullanırken hata ayıklama günlüklerini almak için aşağıdaki ortam değişkenini ayarlayabilirsiniz.

• Service Bus SDK'sından hata ayıklama günlüklerini alma

export DEBUG=azure*

• Service Bus SDK'sından ve protokol düzeyi kitaplığından hata ayıklama günlüklerini alma.

export DEBUG=azure*,rhea*

• İleti dönüştürmesini görüntülemekle ilgilenmiyorsanız (çok fazla konsol/disk alanı tüketir) ortam değişkenini DEBUG aşağıdaki gibi ayarlayabilirsiniz:

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

• Yalnızca hatalarla ilgileniyorsanız ortam değişkenini DEBUG aşağıdaki gibi ayarlayabilirsiniz:

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

Dosyaya oturum açma

1. Ortam değişkenini DEBUG yukarıda gösterildiği gibi ayarlayın
2. Test betiğinizi aşağıdaki gibi çalıştırın:

• Test betiğinizdeki günlük deyimleri adresine out.log , sdk'dan günlük deyimleri ise adresine debug.loggider.

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

• Test betiğinizden ve sdk'dan günlük deyimleri, stderr'ı stdout'a (&1) yeniden yönlendirip stdout'ı bir dosyaya yönlendirerek aynı out.log dosyaya gider:

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

• Test betiğinizden ve sdk'dan günlük deyimleri aynı dosyaya out.loggider.

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

Sonraki adımlar

Service Bus Kuyrukları, Konular ve Abonelikler'e ileti göndermek ve buradan ileti almak için bu kitaplığın nasıl kullanılacağına ilişkin ayrıntılı örnekler için lütfen samples dizinine göz atın.

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.