다음을 통해 공유

JavaScript용 Azure Service Bus 클라이언트 라이브러리 - 버전 7.9.5

  • 아티클

Azure Service Bus 는 Microsoft의 매우 신뢰할 수 있는 클라우드 메시징 서비스입니다.

애플리케이션에서 클라이언트 라이브러리 @azure/service-bus 를 사용하여

  • Azure Service Bus 큐 또는 토픽으로 메시지 보내기
  • Azure Service Bus 큐 또는 구독에서 메시지 받기
  • Azure Service Bus 네임스페이스에서 큐/토픽/구독/규칙 만들기/가져오기/삭제/업데이트/나열

버전 7에 대한 @azure/service-bus 리소스:

주요 링크:

참고: 버전 1.1.10 이하를 사용하고 이 패키지의 최신 버전으로 마이그레이션하려는 경우 Service Bus V1에서 Service Bus V7로 이동하는 마이그레이션 가이드를 참조하세요.

시작

패키지 설치

npm을 사용하여 Azure Service Bus 클라이언트 라이브러리에 대한 최신 버전을 설치합니다.

npm install @azure/service-bus

현재 지원되는 환경

필수 구성 요소

TypeScript 구성

TypeScript 사용자는 노드 형식 정의를 설치해야 합니다.

npm install @types/node

또한 tsconfig.json 사용하도록 설정 compilerOptions.allowSyntheticDefaultImports 해야 합니다. 를 사용하도록 설정한 compilerOptions.esModuleInteropallowSyntheticDefaultImports 경우 는 기본적으로 사용하도록 설정됩니다. 자세한 내용은 TypeScript의 컴파일러 옵션 핸드북 을 참조하세요.

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서를 참조하세요.

이 라이브러리에는 설명된 것 외에도 브라우저에서 제대로 작동하려면 다음 NodeJS 코어 기본 제공 모듈에 대한 추가 폴리필이 필요합니다.

  • buffer
  • os
  • path
  • process

Webpack을 사용하여 번들링

Webpack v5를 사용하는 경우 다음 개발 종속성을 설치할 수 있습니다.

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

그런 다음 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"),
+    },
   },

롤업으로 번들링

롤업 번들러를 사용하는 경우 다음 개발 종속성을 설치합니다.

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

그런 다음 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"],
+    }),
  ]
};

폴리필 사용에 대한 자세한 내용은 즐겨 찾는 번들러 설명서를 참조하세요.

React 네이티브 지원

브라우저와 마찬가지로 React Native는 이 SDK 라이브러리에서 사용하는 일부 JavaScript API를 지원하지 않으므로 폴리필을 제공해야 합니다. 자세한 내용은 Expo를 사용하는 Messaging React 네이티브 샘플을 참조하세요.

클라이언트 인증

Service Bus와의 상호 작용은 ServiceBusClient 클래스의 인스턴스로 시작합니다. 연결 문자열을 사용하거나 Azure Active Directory 자격 증명을 사용하여 Service Bus에 인증할 수 있습니다.

연결 문자열 사용

이 메서드는 Service Bus 인스턴스에 연결 문자열을 사용합니다. Azure Portal에서 연결 문자열을 가져올 수 있습니다.

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

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

이 생성자에 대한 자세한 내용은 API 설명서에서 확인할 수 있습니다.

Azure Active Directory 자격 증명 사용

Azure Active Directory를 사용한 인증은 Azure ID 라이브러리를 사용합니다.

아래 예제에서는 라이브러리에서 사용 가능한 여러 자격 증명 공급자 중 하나인 DefaultAzureCredential을 @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);

참고: AAD에 대한 인터페이스의 고유한 구현을 사용하는 경우 service-bus의 TokenCredential "범위"를 다음으로 설정하여 적절한 토큰을 가져옵니다.

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

이 생성자에 대한 자세한 내용은 API 설명서에서 확인할 수 있습니다.

주요 개념

를 초기화 ServiceBusClient한 후에는 Service Bus 네임스페이스 내에서 이러한 리소스와 상호 작용할 수 있습니다.

  • 큐: 메시지를 보내고 받을 수 있습니다. 지점 간 통신에 자주 사용됩니다.
  • 토픽: 큐와 달리 토픽은 시나리오를 게시/구독하는 데 더 적합합니다. 토픽을 보낼 수 있지만 구독이 필요하며, 그 중 여러 항목을 병렬로 사용할 수 있어야 합니다.
  • 구독: 토픽에서 사용하는 메커니즘입니다. 각 구독은 독립적이며 토픽에 전송된 각 메시지의 복사본을 받습니다. 규칙 및 필터를 사용하여 특정 구독에서 수신되는 메시지를 조정할 수 있습니다.

이러한 리소스에 대한 자세한 내용은 Azure Service Bus란?을 참조하세요.

이러한 리소스와 상호 작용하려면 다음 SDK 개념을 잘 알고 있어야 합니다.

이 라이브러리를 사용하기 전에 큐, 토픽 및 구독을 만들어야 합니다.

예제

다음 섹션에서는 Azure Service Bus를 사용하는 몇 가지 일반적인 작업을 다루는 코드 조각을 제공합니다.

메시지 보내기

클래스의 인스턴스를 ServiceBusClient 만든 후에는 메시지를 보내는 데 사용할 수 있는 createSender 메서드를 사용하여 를 가져올 ServiceBusSender 수 있습니다.

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

메시지 받기

클래스의 인스턴스를 ServiceBusClient 만든 후에는 createReceiver 메서드를 ServiceBusReceiver 사용하여 를 가져올 수 있습니다.

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

사용할 수 있는 두 receiveMode가지가 있습니다.

  • "peekLock" - peekLock 모드에서 수신자가 큐에 지정된 기간 동안 메시지에 대한 잠금을 둡니다.
  • "receiveAndDelete" - receiveAndDelete 모드에서 메시지가 수신되면 Service Bus에서 삭제됩니다.

receiveMode가 옵션에 제공되지 않으면 기본적으로 "peekLock" 모드로 설정됩니다. "peekLock" 모드에서 받은 메시지를 정정 할 수도 있습니다.

다음 세 가지 방법 중 하나로 이 수신기를 사용하여 메시지를 받을 수 있습니다.

메시지 배열 가져오기

메시지 배열로 확인되는 프라미스를 반환하는 receiveMessages 함수를 사용합니다.

const myMessages = await receiver.receiveMessages(10);

메시지 처리기를 사용하여 구독

구독 메서드 를 사용하여 메시지 처리기를 설정하고 필요한 한 실행되도록 합니다.

완료되면 를 호출 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
});

비동기 반복기 사용

getMessageIterator를 사용하여 메시지에 대한 비동기 반복기를 가져옵니다.

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

메시지 해결

메시지가 수신되면 메시지를 해결하는 방법에 따라 받는 사람에서 , abandonMessage()deferMessage() 또는 deadLetterMessage() 를 호출completeMessage()할 수 있습니다.

자세한 내용은 Settling Received Messages를 참조하세요.

배달 못한 편지 큐

배달 못한 편지 큐는 하위 큐입니다. 각 큐 또는 구독에는 자체 배달 못 한 편지 큐가 있습니다. 배달 못 한 편지 큐는 명시적으로 배달 못 한 편지(를 통해 receiver.deadLetterMessage())된 메시지 또는 최대 배달 횟수를 초과한 메시지를 저장합니다.

배달 못한 편지 하위 큐에 대한 수신기를 만드는 것은 구독 또는 큐에 대한 수신기를 만드는 것과 비슷합니다.

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

배달 못한 편지 큐를 보다 철저하게 보여주는 전체 샘플:

세션을 사용하여 메시지 보내기

세션을 사용하려면 세션 사용 큐 또는 구독을 만들어야 합니다. 포털에서 이 기능을 구성하는 방법에 대한 자세한 내용은 여기를 참조 하세요.

세션에 메시지를 보내려면 를 사용하여 ServiceBusClientcreateSender를 사용하여 발신자를 만듭니다.

메시지를 보낼 때 메시지의 sessionId 속성을 설정하여 메시지가 올바른 세션에 있는지 확인합니다.

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

세션 작동 방식에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

세션에서 메시지 받기

세션을 사용하려면 세션 사용 큐 또는 구독을 만들어야 합니다. 포털에서 이 기능을 구성하는 방법에 대한 자세한 내용은 여기를 참조 하세요.

세션 사용이 아닌 큐 또는 구독과 달리, 한 명의 수신기만 언제든지 세션에서 읽을 수 있습니다. 이는 Service Bus에서 처리하는 세션을 잠그 면 적용됩니다. 개념적으로 이는 모드를 사용할 peekLock 때 메시지 잠금이 작동하는 방식과 유사합니다. 메시지(또는 세션)가 잠겨 있는 경우 수신자가 단독으로 액세스할 수 있습니다.

세션을 열고 잠그려면 인스턴스 ServiceBusClient 를 사용하여 SessionReceiver를 만듭니다.

열려는 세션을 선택하는 방법에는 두 가지가 있습니다.

  1. 명명된 sessionId세션을 잠그는 를 지정합니다.

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

  2. 세션 ID를 지정하지 마세요. 이 경우 Service Bus는 아직 잠겨 있지 않은 다음 사용 가능한 세션을 찾습니다.

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

    의 속성을 SessionReceiver통해 sessionId 세션의 이름을 찾을 수 있습니다. receiveMode가 옵션에 제공되지 않으면 기본적으로 "peekLock" 모드로 설정됩니다. "peekLock" 모드에서 받은 메시지를 정정 할 수도 있습니다.

수신기가 만들어지면 다음 세 가지 방법 중에서 선택하여 메시지를 받을 수 있습니다.

세션 작동 방식에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

Service Bus 네임스페이스의 리소스 관리

ServiceBusAdministrationClient 를 사용하면 엔터티(큐, 토픽 및 구독) 및 구독 규칙에 대한 CRUD 작업을 사용하여 네임스페이스를 관리할 수 있습니다.

  • 와 유사한 의 AAD 자격 증명 @azure/identity 뿐만 아니라 서비스 버스 연결 문자열을 사용하여 인증을 ServiceBusClient지원합니다.

참고: Service Bus는 아직 ServiceBusAdministrationClient 네임스페이스에 대한 CORS 규칙 설정을 지원하지 않으므로 웹 보안을 사용하지 않도록 설정하지 않으면 브라우저에서 작동하지 않습니다. 자세한 내용은 여기를 참조 하세요.

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

문제 해결

문제 진단을 시작하는 몇 가지 초기 단계는 다음과 같습니다. 자세한 내용은 Service Bus 문제 해결 가이드를 참조하세요.

AMQP 종속성

Service Bus 라이브러리는 AMQP 프로토콜을 통해 연결을 관리하고 메시지를 보내고 받기 위한 rhea-promise 라이브러리에 따라 달라집니다.

로깅

다음 환경 변수를 설정하여 이 라이브러리를 사용할 때 디버그 로그를 볼 수 있습니다.

  • Service Bus SDK에서 디버그 로그 가져오기
export DEBUG=azure*
  • Service Bus SDK 및 프로토콜 수준 라이브러리에서 디버그 로그를 가져옵니다.
export DEBUG=azure*,rhea*
  • 메시지 변환(콘솔/디스크 공간을 많이 사용)을 보는 데 관심이 없는 경우 다음과 같이 환경 변수를 DEBUG 설정할 수 있습니다.
export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer
  • 오류에만 관심이 있는 경우 다음과 같이 환경 변수를 DEBUG 설정할 수 있습니다.
export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

파일에 로깅

  1. DEBUG 위와 같이 환경 변수 설정
  2. 다음과 같이 테스트 스크립트를 실행합니다.
  • 테스트 스크립트의 로깅 문은 로 out.log 이동하고 sdk의 로깅 문은 로 debug.log이동합니다. 
    node your-test-script.js > out.log 2>debug.log
  • 테스트 스크립트 및 sdk의 로깅 문은 stderr를 stdout(&1)로 리디렉션하여 동일한 파일 out.log 로 이동한 다음 stdout을 파일로 리디렉션합니다.
    node your-test-script.js >out.log 2>&1
  • 테스트 스크립트 및 sdk의 로깅 문은 동일한 파일 out.log로 이동합니다. 
      node your-test-script.js &> out.log

다음 단계

이 라이브러리를 사용하여 Service Bus 큐, 토픽 및 구독으로 메시지를 보내고 받는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

Impressions