Node.js에서 Azure Queue Storage를 사용하는 방법

아티클
01/20/2023

개요

이 가이드는 Azure Queue Storage를 사용하여 일반적인 시나리오를 수행하는 방법을 보여 줍니다. 샘플은 Node.js API를 사용하여 작성되었습니다. 여기서 다루는 시나리오에는 큐 메시지의 삽입, 피킹(peeking), 가져오기 및 삭제가 포함됩니다. 큐를 만들고 삭제하는 방법에 대해서도 알아봅니다.

Queue Storage란?

Azure Queue Storage는 HTTP 또는 HTTPS를 사용하여 인증된 호출을 통해 전 세계 어디에서나 액세스할 수 있는 다수의 메시지를 저장하기 위한 서비스입니다. 단일 큐 메시지의 크기는 최대 64KB일 수 있으며, 하나의 큐에 스토리지 계정의 총 용량 제한까지 수백만 개의 메시지가 포함될 수 있습니다. Queue Storage는 비동기적으로 처리할 작업의 백로그를 만드는 데 자주 사용됩니다.

큐 서비스 개념

Azure 큐 서비스에는 다음 구성 요소가 포함됩니다.

Azure 큐 서비스 구성 요소

Storage 계정: Azure Storage에 대한 모든 액세스는 Storage 계정을 통해 수행됩니다. 스토리지 계정에 대한 자세한 내용은 스토리지 계정 개요를 참조하세요.
큐: 큐에는 메시지 집합이 포함됩니다. 모든 메시지는 큐에 있어야 합니다. 큐 이름은 모두 소문자여야 합니다. 큐의 명명에 대한 자세한 내용은 큐 및 메타데이터 명명을 참조하세요.
메시지: 최대 64KB인 임의 형식의 메시지입니다. 메시지가 큐에 남아 있을 수 있는 최대 시간은 7일입니다. 2017-07-29 이상 버전에서 허용되는 최대 TTL(Time to Live)은 모든 양수 또는 메시지가 만료되지 않는 -1입니다. 이 매개 변수를 생략하면 기본 TTL(Time to Live)은 7일입니다.
URL 형식: 큐는 http://<storage account>.queue.core.windows.net/<queue> URL 형식을 사용하여 주소를 지정할 수 있습니다.

다음 URL은 다이어그램에 있는 큐의 주소를 지정합니다.

http://myaccount.queue.core.windows.net/incoming-orders

Azure Storage 계정 만들기

첫 번째 Azure Storage 계정을 가장 쉽게 만드는 방법은 Azure Portal을 사용하는 것입니다. 자세한 내용은 스토리지 계정 만들기를 참조하십시오.

또한 Azure PowerShell, Azure CLI 또는 .NET용 Azure Storage 리소스 공급자를 사용하여 Azure 스토리지 계정을 만들 수도 있습니다.

이 시점에서 스토리지 계정을 Azure에 만들지 않으려는 경우 Azurite 스토리지 에뮬레이터를 사용하여 로컬 환경에서 코드를 실행하고 테스트할 수도 있습니다. 자세한 내용은 로컬 Azure Storage 개발에 Azurite 에뮬레이터 사용을 참조하세요.

Node.js 애플리케이션 만들기

빈 Node.js 애플리케이션을 만들려면 Azure App Service에서 Node.js 웹앱 만들기, Azure Cloud Service에 Node.js 애플리케이션 빌드 및 배포(PowerShell 사용) 또는 Visual Studio Code를 참조하세요.

스토리지에 액세스하도록 애플리케이션 구성

JavaScript용 Azure Storage 클라이언트 라이브러리에는 스토리지 REST 서비스와 통신하는 편리한 라이브러리 집합이 포함되어 있습니다.

NPM(Node Package Manager)을 사용하여 패키지 가져오기

PowerShell(Windows), Terminal(Mac) 또는 Bash (Unix)과 같은 명령줄 인터페이스를 사용하여 샘플 애플리케이션을 만든 폴더로 이동합니다.
명령 창에 npm install @azure/storage-queue를 입력합니다.
node_modules 폴더가 만들어졌는지 확인합니다. 이 폴더에서 스토리지에 액세스하는 데 필요한 클라이언트 라이브러리가 들어 있는 @azure/storage-queue 패키지를 찾습니다.

패키지 가져오기

코드 편집기를 사용하여 큐를 사용하려는 JavaScript 파일의 맨 위에 다음을 추가합니다.

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

큐를 만드는 방법

다음 코드는 AZURE_STORAGE_CONNECTION_STRING이라는 환경 변수의 값을 가져와서 QueueServiceClient 개체를 만드는 데 사용합니다. 이 개체는 특정 큐에 대해 작업할 수 있는 QueueClient 개체를 만드는 데 사용됩니다.

// Retrieve the connection from an environment
// variable called AZURE_STORAGE_CONNECTION_STRING
const connectionString = process.env.AZURE_STORAGE_CONNECTION_STRING;

// Create a unique name for the queue
const queueName = "myqueue-" + Date.now().toString();

console.log("Creating queue: ", queueName);

// Instantiate a QueueServiceClient which will be used
// to create a QueueClient and to list all the queues
const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

// Get a QueueClient which will be used
// to create and manipulate a queue
const queueClient = queueServiceClient.getQueueClient(queueName);

// Create the queue
await queueClient.create();

큐가 이미 있으면 예외가 throw됩니다.

메시지의 서식을 지정하는 방법

메시지 유형이 문자열입니다. 모든 메시지는 문자열로 처리됩니다. 다른 데이터 형식을 보내야 하는 경우 메시지를 보낼 때 해당 데이터 형식을 문자열로 직렬화하고 메시지를 읽을 때 문자열 형식을 역직렬화해야 합니다.

JSON을 문자열 형식으로 변환하고 Node.js 다시 변환하려면 다음 도우미 함수를 사용합니다.

function jsonToBase64(jsonObj) {
    const jsonString = JSON.stringify(jsonObj)
    return  Buffer.from(jsonString).toString('base64')
}
function encodeBase64ToJson(base64String) {
    const jsonString = Buffer.from(base64String,'base64').toString()
    return JSON.parse(jsonString)
}

큐에 메시지를 삽입하는 방법

큐에 메시지를 추가하려면 sendMessage 메서드를 호출합니다.

messageText = "Hello, World";
console.log("Adding message to the queue: ", messageText);

// Add a message to the queue
await queueClient.sendMessage(messageText);

다음 메시지를 피킹하는 방법

peekMessages 메서드를 호출하여 큐에서 제거하지 않고 큐에서 메시지를 피킹할 수 있습니다.

기본적으로 peekMessages는 단일 메시지를 읽습니다. 다음 예에서는 큐의 처음 5개 메시지를 봅니다. 5개 미만의 메시지가 표시되면 표시되는 메시지만 반환됩니다.

// Peek at messages in the queue
const peekedMessages = await queueClient.peekMessages({ numberOfMessages: 5 });

for (i = 0; i < peekedMessages.peekedMessageItems.length; i++) {
    // Display the peeked message
    console.log("Peeked message: ", peekedMessages.peekedMessageItems[i].messageText);
}

큐에 메시지가 없을 때 peekMessages를 호출하면 오류가 반환되지 않습니다. 그러나 메시지는 반환되지 않습니다.

대기 중인 메시지의 콘텐츠 변경 방법

다음 예에서는 메시지의 텍스트를 업데이트합니다.

updateMessage를 호출하여 큐에 있는 메시지의 콘텐츠를 변경합니다.

// Get the first message in the queue
var receivedMessages = await queueClient.receiveMessages();
const firstMessage = receivedMessages.receivedMessageItems[0];

// Update the received message
await queueClient.updateMessage(
    firstMessage.messageId,
    firstMessage.popReceipt,
    "This message has been updated"
);

메시지를 큐에서 제거하는 방법

메시지를 큐에서 제거 작업은 2단계 프로세스입니다.

메시지를 받습니다.
메시지를 삭제합니다.

다음 예에서는 메시지를 가져온 후 삭제합니다.

메시지를 받으려면 receiveMessages 메서드를 호출합니다. 이 호출을 수행하면 메시지가 큐에 표시되지 않으므로 다른 클라이언트에서 메시지를 처리할 수 없습니다. 애플리케이션에서 메시지를 처리하고 나면 deleteMessage를 호출하여 큐에서 삭제합니다.

// Get next message from the queue
receivedMessages = await queueClient.receiveMessages();
var message = receivedMessages.receivedMessageItems[0];

console.log("Dequeuing message: ", message.messageText);

await queueClient.deleteMessage(message.messageId, message.popReceipt);

기본적으로 메시지는 30초 동안만 숨겨집니다. 30초 후에는 다른 클라이언트에 표시됩니다. receiveMessages를 호출할 때 options.visibilityTimeout을 설정하여 다른 값을 지정할 수 있습니다.

큐에 메시지가 없을 때 receiveMessages를 호출하면 오류가 반환되지 않습니다. 그러나 메시지는 반환되지 않습니다.

큐에서 메시지를 제거하는 추가 옵션

큐에서 메시지 검색을 사용자 지정할 수 있는 방법으로는 두 가지가 있습니다.

options.numberOfMessages: 메시지 배치를 검색합니다(최대 32개).
options.visibilityTimeout: 표시하지 않는 시간 제한을 더 길거나 짧게 설정합니다.

다음 예는 receiveMessages 메서드를 사용하여 한 번 호출에 5개의 메시지를 가져옵니다. 그런 다음에 for 루프를 사용하여 각 메시지를 처리합니다. 또한 이 메서드에서 반환되는 모든 메시지의 표시하지 않는 시간 제한을 5분으로 설정합니다.

// Get up to 5 messages from the queue
const receivedMsgsResp = await queueClient.receiveMessages({ numberOfMessages: 5, visibilityTimeout: 5 * 60 });

for (i = 0; i < receivedMsgsResp.receivedMessageItems.length; i++)
{
    message = receivedMsgsResp.receivedMessageItems[i];
    console.log("Dequeuing message: ", message.messageText);
    await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

큐 길이를 가져오는 방법

getProperties 메서드는 큐에서 대기 중인 대략적인 메시지 수를 포함하여 큐에 대한 메타데이터를 반환합니다.

const properties = await queueClient.getProperties();
console.log("Approximate queue length: ", properties.approximateMessagesCount);

큐를 나열하는 방법

큐 목록을 검색하려면 QueueServiceClient.listQueues를 호출합니다. 특정 접두사로 필터링된 목록을 검색하려면 listQueues에 대한 호출에서 options.prefix를 설정합니다.

for await (const item of queueServiceClient.listQueues()) {
  console.log("Queue: ", item.name);
}

큐를 삭제하는 방법

큐와 큐에 포함된 모든 메시지를 삭제하려면 QueueClient 개체의 DeleteQueue 메서드를 호출합니다.

// Delete the queue
console.log("Deleting queue: ", queueClient.name);
await queueClient.delete();

큐를 삭제하지 않고 모든 메시지를 지우려면 ClearMessages를 호출합니다.

팁

Azure Storage 코드 샘플 리포지토리 확인

다운로드하고 실행할 수 있는 엔드투엔드 Azure Storage 코드 샘플을 쉽게 사용하려면 Azure Storage 샘플 목록을 확인하세요.

다음 단계

이제 Queue Storage의 기본 사항을 배웠으므로 다음 링크를 따라 좀 더 복잡한 스토리지 작업에 대해 알아보세요.

새로운 기능을 알아보려면 Azure Storage 팀 블로그를 방문하세요.
GitHub의 JavaScript용 Azure Storage 클라이언트 라이브러리 리포지토리를 방문하세요.

다음을 통해 공유