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

아티클
07/24/2024

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

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

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

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

키 링크:

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

시작

현재 지원되는 환경

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

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

필수 구성 요소

패키지 설치

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에 따라 달라집니다.

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 매개 변수의 일부 설정을 허용합니다.

`@azure/identity` 패키지의 `DefaultAzureCredential`

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경우에만 해당]

연결 문자열 사용

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

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

`StorageSharedKeyCredential`

또는 계정 이름 및 계정 키를 인수로 전달하여 StorageSharedKeyCredential 사용하여 QueueServiceClient 인스턴스화합니다. (계정 이름 및 계정 키는 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() {
  let 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() {
  let 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설정합니다. 또는 @azure/loggersetLogLevel 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

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

setLogLevel("info");

다음 단계

추가 코드 샘플

기여

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

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

다음을 통해 공유

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

시작

현재 지원되는 환경

필수 구성 요소

패키지 설치

클라이언트 인증

Azure Active Directory

호환성

웹 작업자

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

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

JavaScript 번들

CORS

주요 개념

예제

패키지 가져오기

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

`@azure/identity` 패키지의 `DefaultAzureCredential`

연결 문자열 사용

`StorageSharedKeyCredential`

SAS 토큰으로

이 계정의 큐 나열

새 큐 만들기

큐에 메시지 보내기

메시지 피킹

메시지 처리

큐 삭제

문제 해결

다음 단계

기여

추가 리소스

다음을 통해 공유

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

시작

현재 지원되는 환경

필수 구성 요소

패키지 설치

클라이언트 인증

Azure Active Directory

호환성

웹 작업자

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

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

JavaScript 번들

CORS

주요 개념

예제

패키지 가져오기

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

@azure/identity 패키지의 DefaultAzureCredential

연결 문자열 사용

StorageSharedKeyCredential

SAS 토큰으로

이 계정의 큐 나열

새 큐 만들기

큐에 메시지 보내기

메시지 피킹

메시지 처리

큐 삭제

문제 해결

다음 단계

기여

추가 리소스

`@azure/identity` 패키지의 `DefaultAzureCredential`

`StorageSharedKeyCredential`