JavaScript용 Azure Storage 큐 클라이언트 라이브러리 - 버전 12.25.0

Azure Storage 큐는 애플리케이션 구성 요소 간에 클라우드 메시징을 제공합니다. 크기 조정을 위해 애플리케이션을 디자인할 때 애플리케이션 구성 요소는 독립적으로 확장할 수 있도록 분리되는 경우가 많습니다. Queue Storage는 클라우드, 데스크톱, 온-프레미스 서버 또는 모바일 디바이스에서 실행되는 애플리케이션 구성 요소 간의 통신을 위한 비동기 메시징을 제공합니다. 또한 Queue Storage는 비동기 작업 관리 및 프로세스 작업 흐름 빌드를 지원합니다.

이 프로젝트는 Azure Storage 큐 서비스를 쉽게 사용할 수 있는 JavaScript의 클라이언트 라이브러리를 제공합니다.

이 패키지의 클라이언트 라이브러리를 사용하여 다음을 수행합니다.

• 큐 서비스 속성 가져오기/설정
• 큐 만들기/나열/삭제
• 큐 메시지 보내기/받기/피킹/지우기/업데이트/삭제

키 링크:

• 소스 코드
• 패키지(npm)
• API 참조 설명서
• 제품 설명서
• 샘플
• Azure Storage Queue REST API

시작

현재 지원되는 환경

• Node.js의 LTS 버전
• Safari, Chrome, Edge 및 Firefox의 최신 버전입니다.

자세한 내용은 지원 정책 참조하세요.

필수 구성 요소

• Azure 구독
• Storage 계정

패키지 설치

JavaScript용 Azure Storage 큐 클라이언트 라이브러리를 설치하는 기본 방법은 npm 패키지 관리자를 사용하는 것입니다. 터미널 창에 다음을 입력합니다.

npm install @azure/storage-queue

클라이언트 인증

Azure Storage는 인증하는 여러 가지 방법을 지원합니다. Azure Queue Storage 서비스와 상호 작용하려면 스토리지 클라이언트의 인스턴스(예: QueueServiceClient 또는 QueueClient)를 만들어야 합니다. 인증에 대한 자세한 내용은 만들기 위한 샘플을 참조하세요.

• Azure Active Directory
• 공유 키
• 공유 액세스 서명

Azure Active Directory

Azure Queue Storage 서비스는 Azure Active Directory를 사용하여 해당 API에 대한 요청을 인증하도록 지원합니다. @azure/identity 패키지는 애플리케이션에서 이 작업을 수행하는 데 사용할 수 있는 다양한 자격 증명 유형을 제공합니다. 시작하기 위한 자세한 내용 및 샘플은 대한 추가 정보를 참조하세요.

호환성

이 라이브러리는 Node.js 및 브라우저와 호환되며 LTS Node.js 버전(>=8.16.0) 및 최신 버전의 Chrome, Firefox 및 Edge에 대해 유효성을 검사합니다.

웹 작업자

이 라이브러리를 사용하려면 브라우저에서 사용할 때 특정 DOM 개체를 전역적으로 사용할 수 있어야 하며, 웹 작업자는 기본적으로 사용할 수 없습니다. 이 라이브러리가 웹 작업자에서 작동하도록 하려면 이러한 라이브러리를 폴리필해야 합니다.

자세한 내용은 Web Worker JS용 Azure SDK 사용에 대한 설명서를 참조하세요.

이 라이브러리는 웹 작업자에서 사용할 때 로드된 외부 폴리필이 필요한 다음 DOM API에 따라 달라집니다.

• document
• DOMParser
• Node
• XMLSerializer

Node.js 브라우저 간의 차이점

Node.js 브라우저 런타임 간에는 차이가 있습니다. 이 라이브러리를 시작할 때는 "NODE.JS 런타임에서만 사용 가능" 또는 "브라우저에서만 사용 가능"표시된 API 또는 클래스에 주의하세요.

다음 기능, 인터페이스, 클래스 또는 함수는 Node.js

• 계정 이름 및 계정 키를 기반으로 하는 공유 키 권한 부여
  • StorageSharedKeyCredential
• SAS(공유 액세스 서명) 생성
  • generateAccountSASQueryParameters()
  • generateQueueSASQueryParameters()

JavaScript 번들

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

CORS

브라우저용으로 개발해야 하는 경우 스토리지 계정에 대한 CORS(원본 간 리소스 공유) 규칙을 설정해야 합니다. Azure Portal 및 Azure Storage Explorer로 이동하여 스토리지 계정을 찾고 Blob/큐/파일/테이블 서비스에 대한 새 CORS 규칙을 만듭니다.

예를 들어 디버깅을 위해 다음 CORS 설정을 만들 수 있습니다. 그러나 프로덕션 환경의 요구 사항에 따라 설정을 신중하게 사용자 지정하세요.

• 허용된 원본: *
• 허용되는 동사: DELETE, GET, HEAD,MERGE,POST,OPTIONS,PUT
• 허용되는 헤더: *
• 노출된 헤더: *
• 최대 사용 기간(초): 86400

주요 개념

큐는 연결된 클라이언트 간에 메시지를 보내거나 받기 위한 Azure Storage 큐 서비스 계정 내의 데이터 저장소입니다.

이러한 서비스와 관련된 라이브러리의 주요 데이터 형식은 다음과 같습니다.

• Azure Storage 큐 서비스에서 지정된 스토리지 계정에 대한 연결(URL을 통해)을 나타내며 해당 큐를 조작하기 위한 API를 제공합니다. 서비스에 인증되며 서비스에서 큐를 만들고 삭제하고 나열할 뿐만 아니라 QueueClient 개체를 만드는 데 사용할 수 있습니다.
• QueueClient 스토리지 계정의 단일 큐 나타냅니다. 큐의 메시지를 보내고, 받고, 피킹하는 등 큐의 메시지를 조작하는 데 사용할 수 있습니다.

예제

패키지 가져오기

클라이언트를 사용하려면 패키지를 파일로 가져옵니다.

const AzureStorageQueue = require("@azure/storage-queue");

또는 필요한 형식만 선택적으로 가져옵니다.

const { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");

큐 서비스 클라이언트 만들기

QueueServiceClient 큐 서비스에 대한 URL과 액세스 자격 증명이 필요합니다. 또한 필요에 따라 options 매개 변수의 일부 설정을 허용합니다.

DefaultAzureCredential 패키지의 @azure/identity

QueueServiceClient 인스턴스화하는 권장 방법

설치 : 참조 - 클라이언트 애플리케이션에서 Azure Active Directory를 사용하여 Blob 및 큐에 대한 액세스 권한 부여 - /azure/storage/common/storage-auth-aad-app

• 새 AAD 애플리케이션을 등록하고 로그인한 사용자를 대신하여 Azure Storage에 액세스할 수 있는 권한을 부여합니다.

  • Azure Active Directory(azure-Portal)에 새 애플리케이션 등록 - /azure/active-directory/develop/quickstart-register-app
  • API permissions 섹션에서 Add a permission 선택하고 Microsoft APIs선택합니다.
  • Azure Storage 선택하고 user_impersonation 옆에 있는 확인란을 선택한 다음 Add permissions클릭합니다. 이렇게 하면 애플리케이션이 로그인한 사용자를 대신하여 Azure Storage에 액세스할 수 있습니다.

• Azure Portal에서 RBAC를 사용하여 Azure Storage 큐 데이터에 대한 액세스 권한 부여

  • Blob 및 큐에 대한 RBAC 역할 - /azure/storage/common/storage-auth-aad-rbac-portal.
  • Azure Portal에서 스토리지 계정으로 이동하여 Access control (IAM) 탭(azure-portal의 스토리지 계정 왼쪽 탐색 모음)에서 등록된 AAD 애플리케이션에 Storage 큐 데이터 기여자 역할을 할당합니다.

• 샘플에 대한 환경 설정

  • AAD 애플리케이션의 개요 페이지에서 CLIENT ID 적어두고 TENANT ID. "인증서 & 비밀" 탭에서 비밀을 만들고 기록해 둡니다.
  • 샘플을 성공적으로 실행하기 위한 환경 변수로 AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET 있는지 확인합니다(process.env를 활용할 수 있습니다).

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

[참고 - 위의 단계는 Node.js경우에만 해당]

연결 문자열 사용

또는 전체 연결 문자열을 인수로 사용하여 QueueServiceClient 정적 메서드를 사용하여 fromConnectionString() 인스턴스화할 수 있습니다. (연결 문자열은 Azure Portal에서 가져올 수 있습니다.) [NODE.JS 런타임에서만 사용 가능]

const { QueueServiceClient } = require("@azure/storage-queue");

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

StorageSharedKeyCredential

또는 계정 이름 및 계정 키를 인수로 전달하여 QueueServiceClient 사용하여 StorageSharedKeyCredential 인스턴스화합니다. (계정 이름 및 계정 키는 Azure Portal에서 가져올 수 있습니다.) [NODE.JS 런타임에서만 사용 가능]

const { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  sharedKeyCredential,
  {
    retryOptions: { maxTries: 4 }, // Retry options
    telemetry: { value: "BasicSample/V11.0.0" } // Customized telemetry string
  }
);

SAS 토큰으로

또한 SAS(공유 액세스 서명)를 사용하여 QueueServiceClient 인스턴스화할 수 있습니다. Azure Portal에서 SAS 토큰을 가져오거나 generateAccountSASQueryParameters()사용하여 SAS 토큰을 생성할 수 있습니다.

const { QueueServiceClient } = require("@azure/storage-queue");
const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net${sas}`
);

이 계정의 큐 나열

QueueServiceClient.listQueues() 함수를 사용하여 새 for-await-of 구문을 사용하여 큐를 반복합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

async function main() {
  const iter1 = queueServiceClient.listQueues();
  let i = 1;
  for await (const item of iter1) {
    console.log(`Queue${i}: ${item.name}`);
    i++;
  }
}

main();

또는 for-await-of없는 경우:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

async function main() {
  const iter2 = queueServiceClient.listQueues();
  let i = 1;
  let item = await iter2.next();
  while (!item.done) {
    console.log(`Queue ${i++}: ${item.value.name}`);
    item = await iter2.next();
  }
}

main();

큐 반복에 대한 전체 샘플은 samples/v12/typescript/listQueues.ts참조하세요.

새 큐 만들기

QueueServiceClient.getQueueClient() 함수를 사용하여 새 큐를 만듭니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const createQueueResponse = await queueClient.create();
  console.log(
    `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`
  );
}

main();

큐에 메시지 보내기

sendMessage() 사용하여 큐에 메시지를 추가합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  // Send a message into the queue using the sendMessage method.
  const sendMessageResponse = await queueClient.sendMessage("Hello World!");
  console.log(
    `Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`
  );
}

main();

메시지 피킹

QueueClient.peekMessages() 큐 앞에서 하나 이상의 메시지를 볼 수 있습니다. 이 호출은 다른 코드가 피킹된 메시지에 액세스하는 것을 방지하지 않습니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const peekMessagesResponse = await queueClient.peekMessages();
  console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);
}

main();

메시지 처리

메시지는 두 단계로 처리됩니다.

• 먼저 queueClient.receiveMessages()호출합니다. 이렇게 하면 기본 기간 30초 동안 이 큐에서 메시지를 읽는 다른 코드에 메시지가 보이지 않습니다.
• 메시지 처리가 완료되면 메시지의 popReceipt사용하여 queueClient.deleteMessage() 호출합니다.

코드가 하드웨어 또는 소프트웨어 오류로 인해 메시지를 처리하지 못하는 경우 이 2단계 프로세스는 코드의 다른 인스턴스가 동일한 메시지를 가져와서 다시 시도할 수 있도록 합니다.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const response = await queueClient.receiveMessages();
  if (response.receivedMessageItems.length === 1) {
    const receivedMessageItem = response.receivedMessageItems[0];
    console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`);
    const deleteMessageResponse = await queueClient.deleteMessage(
      receivedMessageItem.messageId,
      receivedMessageItem.popReceipt
    );
    console.log(
      `Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`
    );
  }
}

main();

큐 삭제

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
);

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const deleteQueueResponse = await queueClient.delete();
  console.log(
    `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`
  );
}

main();

간단한 QueueServiceClient 시나리오의 전체 예는 samples/v12/typescript/src/queueClient.ts.

문제 해결

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info설정합니다. 또는 setLogLevel@azure/logger 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

다음 단계

추가 코드 샘플

• Queue Storage 샘플
• Queue Storage 테스트 사례

기여

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

또한 스토리지 라이브러리에 대한 테스트 환경 설정에 대한 자세한 내용은 Storage 관련 가이드 참조하세요.