Python용 Azure Storage 큐 클라이언트 라이브러리 - 버전 12.9.0

  • 아티클

Azure Queue Storage는 HTTP 또는 HTTPS를 사용하여 인증된 호출을 통해 전 세계 어디에서나 액세스할 수 있는 다수의 메시지를 저장하기 위한 서비스입니다. 단일 큐 메시지의 크기는 최대 64KiB이고 큐에는 스토리지 계정의 총 용량 제한까지 수백만 개의 메시지가 포함될 수 있습니다.

Queue Storage의 일반적인 사용은 다음과 같습니다.

  • 비동기적으로 처리할 작업 백로그 만들기
  • 분산 애플리케이션의 여러 부분 간에 메시지 전달

소스 코드 | 패키지(PyPI) | 패키지(Conda) | API 참조 설명서 | 제품 설명서 | 샘플

시작

필수 구성 요소

패키지 설치

pip를 사용하여 Python용 Azure Storage 큐 클라이언트 라이브러리를 설치합니다.

pip install azure-storage-queue

저장소 계정 만들기

새 스토리지 계정을 만들려는 경우 Azure Portal, Azure PowerShell 또는 Azure CLI를 사용할 수 있습니다.

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

클라이언트 만들기

Python용 Azure Storage 큐 클라이언트 라이브러리를 사용하면 스토리지 계정 자체, 큐 및 메시지의 세 가지 유형의 리소스와 상호 작용할 수 있습니다. 이러한 리소스와의 상호 작용은 클라이언트의 instance 시작합니다. 클라이언트 개체를 만들려면 스토리지 계정의 큐 서비스 엔드포인트 URL과 스토리지 계정에 액세스할 수 있는 자격 증명이 필요합니다.

from azure.storage.queue import QueueServiceClient

service = QueueServiceClient(account_url="https://<my-storage-account-name>.queue.core.windows.net/", credential=credential)

계정 URL 조회

Azure Portal, Azure PowerShell 또는 Azure CLI를 사용하여 스토리지 계정의 큐 서비스 URL을 찾을 수 있습니다.

# Get the queue service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.queue"

자격 증명 유형

매개 변수는 credential 사용하려는 권한 부여 유형에 따라 다양한 형태로 제공될 수 있습니다.

  1. SAS(공유 액세스 서명) 토큰을 사용하려면 토큰을 문자열로 제공합니다. 계정 URL에 SAS 토큰이 포함된 경우 자격 증명 매개 변수를 생략합니다. "공유 액세스 서명"에서 Azure Portal에서 SAS 토큰을 생성하거나 함수 중 generate_sas() 하나를 사용하여 스토리지 계정 또는 큐에 대한 sas 토큰을 만들 수 있습니다.

    from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    start=datetime.utcnow(),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

  2. 스토리지 계정 공유 키 (즉, 계정 키 또는 액세스 키)를 사용하려면 키를 문자열로 제공합니다. 이는 Azure Portal의 "액세스 키" 섹션 아래 또는 다음 Azure CLI 명령을 실행하여 찾을 수 있습니다.

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    키를 자격 증명 매개 변수로 사용하여 클라이언트를 인증합니다.

    from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")

  3. AAD(Azure Active Directory) 토큰 자격 증명을 사용하려면 azure-identity 라이브러리에서 가져온 원하는 자격 증명 형식의 instance 제공합니다. 예를 들어 DefaultAzureCredential을 사용하여 클라이언트를 인증할 수 있습니다.

    이렇게 하려면 몇 가지 초기 설정이 필요합니다.

    반환된 토큰 자격 증명을 사용하여 클라이언트를 인증합니다.

        from azure.identity import DefaultAzureCredential
    from azure.storage.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )

연결 문자열 클라이언트 만들기

사용 사례 및 권한 부여 방법에 따라 계정 URL과 자격 증명을 별도로 제공하는 대신 스토리지 연결 문자열 사용하여 클라이언트 instance 초기화하는 것이 좋습니다. 이렇게 하려면 스토리지 연결 문자열 클라이언트의 from_connection_string 클래스 메서드에 전달합니다.

from azure.storage.queue import QueueServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = QueueServiceClient.from_connection_string(conn_str=connection_string)

스토리지 계정에 대한 연결 문자열은 "액세스 키" 섹션 아래의 Azure Portal 또는 다음 CLI 명령을 실행하여 찾을 수 있습니다.

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

주요 개념

다음 구성 요소는 Azure Queue Service를 구성합니다.

  • 스토리지 계정 자체
  • 메시지 집합을 포함하는 스토리지 계정 내의 큐
  • 최대 64KiB의 모든 형식으로 큐 내의 메시지

Python용 Azure Storage 큐 클라이언트 라이브러리를 사용하면 전용 클라이언트 개체를 사용하여 이러한 각 구성 요소와 상호 작용할 수 있습니다.

비동기 클라이언트

이 라이브러리에는 Python 3.5 이상에서 지원되는 완전한 비동기 API가 포함되어 있습니다. 이를 사용하려면 먼저 aiohttp와 같은 비동기 전송을 설치해야 합니다. 자세한 내용은 azure-core 설명서를 참조하세요.

비동기 클라이언트 및 자격 증명은 더 이상 필요하지 않은 경우 닫아야 합니다. 이러한 개체는 비동기 컨텍스트 관리자이며 비동기 close 메서드를 정의합니다.

클라이언트

큐 서비스의 다양한 구성 요소와 상호 작용하기 위해 두 개의 서로 다른 클라이언트가 제공됩니다.

  1. QueueServiceClient - 이 클라이언트는 Azure Storage 계정 자체와의 상호 작용을 나타내며 미리 구성된 클라이언트 인스턴스를 획득하여 내 큐에 액세스할 수 있습니다. 계정 속성을 검색 및 구성하고 계정 내에서 큐를 나열, 만들기 및 삭제하는 작업을 제공합니다. 특정 큐에서 작업을 수행하려면 메서드를 사용하여 클라이언트를 검색합니다 get_queue_client .
  2. QueueClient - 이 클라이언트는 특정 큐와의 상호 작용을 나타냅니다(아직 존재하지 않아도 됨). 큐를 만들거나 삭제하거나 구성하는 작업을 제공하며 큐 내에서 메시지를 보내고, 받고, 피킹하고, 삭제하고, 업데이트하는 작업을 포함합니다.

메시지

  • 보내기 - 큐에 메시지를 추가하고 필요에 따라 메시지에 대한 표시 시간 제한을 설정합니다.
  • 수신 - 큐에서 메시지를 검색하여 다른 소비자에게 보이지 않게 합니다.
  • Peek - 메시지 표시 유형을 변경하지 않고 큐 앞부분에서 메시지를 검색합니다.
  • 업데이트 - 메시지 및/또는 메시지 내용의 표시 시간 제한을 업데이트.
  • 삭제 - 큐에서 지정된 메시지를 삭제합니다.
  • 지우기 - 큐에서 모든 메시지를 지웁니다.

예제

다음 섹션에서는 다음을 포함하여 가장 일반적인 스토리지 큐 작업 중 일부를 다루는 몇 가지 코드 조각을 제공합니다.

큐 만들기

스토리지 계정에 큐 만들기

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.create_queue()

비동기 클라이언트를 사용하여 큐 만들기

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await queue.create_queue()

메시지 보내기

큐에 메시지 보내기

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

비동기적으로 메시지 보내기

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

메시지 수신

큐에서 메시지 수신 및 처리

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

일괄 처리로 메시지 수신 및 처리

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

메시지를 비동기적으로 수신 및 처리

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

선택적 구성

클라이언트 및 작업별 수준에서 전달할 수 있는 선택적 키워드(keyword) 인수입니다.

정책 구성 다시 시도

클라이언트를 인스턴스화하여 다시 시도 정책을 구성할 때 다음 키워드(keyword) 인수를 사용합니다.

  • retry_total (int): 허용할 총 재시도 횟수입니다. 다른 개수보다 우선합니다. retry_total=0 요청을 다시 시도하지 않으려면 전달합니다. 기본값은 10입니다.
  • retry_connect (int): 다시 시도할 연결 관련 오류 수입니다. 기본값은 3입니다.
  • retry_read (int): 읽기 오류를 다시 시도할 횟수입니다. 기본값은 3입니다.
  • retry_status(int): 잘못된 상태 코드에서 다시 시도할 횟수입니다. 기본값은 3입니다.
  • retry_to_secondary (bool): 가능하면 요청을 보조로 다시 시도해야 하는지 여부입니다. RA-GRS 계정만 사용하도록 설정해야 하며 잠재적으로 부실한 데이터를 처리할 수 있습니다. 기본값은 False입니다.

기타 클라이언트/작업별 구성

클라이언트 또는 작업별로 지정할 수 있는 다른 선택적 구성 키워드(keyword) 인수입니다.

클라이언트 키워드(keyword) 인수:

  • connection_timeout (int): 클라이언트가 서버에 대한 연결을 설정하기 위해 대기하는 시간(초)입니다. 기본값은 20초입니다.
  • read_timeout (int): 클라이언트가 서버의 응답을 위해 연속 읽기 작업 사이에 대기하는 시간(초)입니다. 소켓 수준 시간 제한이며 전체 데이터 크기의 영향을 받지 않습니다. 클라이언트 쪽 읽기 시간 제한은 자동으로 다시 시도됩니다. 기본값은 60초입니다.
  • transport (Any): HTTP 요청을 보내기 위해 사용자가 제공한 전송입니다.

작업별 키워드(keyword) 인수:

  • raw_response_hook (호출 가능): 지정된 콜백은 서비스에서 반환된 응답을 사용합니다.
  • raw_request_hook (호출 가능): 지정된 콜백은 서비스로 전송되기 전에 요청을 사용합니다.
  • client_request_id (str): 선택적 사용자 지정 요청 ID입니다.
  • user_agent (str): 요청과 함께 보낼 사용자 에이전트 헤더에 사용자 지정 값을 추가합니다.
  • logging_enable (bool): DEBUG 수준에서 로깅을 사용하도록 설정합니다. 기본값은 False입니다. 클라이언트 수준에서 전달하여 모든 요청에 사용할 수도 있습니다.
  • logging_body (bool): 요청 및 응답 본문을 로깅할 수 있습니다. 기본값은 False입니다. 클라이언트 수준에서 전달하여 모든 요청에 사용할 수도 있습니다.
  • 헤더 (dict): 사용자 지정 헤더를 키, 값 쌍으로 전달합니다. 예: headers={'CustomValue': value}

문제 해결

일반

스토리지 큐 클라이언트는 Azure Core에 정의된 예외를 발생합니다.

이 목록은 throw된 예외를 catch하는 참조에 사용할 수 있습니다. 예외의 특정 오류 코드를 얻으려면 특성(예exception.error_code: )을 사용합니다error_code.

로깅

이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 INFO 수준에서 기록됩니다.

요청/응답 본문 및 수정되지 않은 헤더를 포함한 자세한 DEBUG 수준 로깅은 인수가 있는 클라이언트 logging_enable 에서 사용하도록 설정할 수 있습니다.

import sys
import logging
from azure.storage.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = QueueServiceClient.from_connection_string("your_connection_string", logging_enable=True)

마찬가지로 logging_enable은 클라이언트에 대해 상세 로깅을 사용하지 않는 경우에도 한 작업에만 사용하게 설정할 수 있습니다.

service_client.get_service_stats(logging_enable=True)

다음 단계

추가 샘플 코드

큐 샘플을 시작합니다.

SDK의 GitHub 리포지토리에서 여러 스토리지 큐 Python SDK 샘플을 사용할 수 있습니다. 이러한 샘플은 스토리지 큐를 사용하는 동안 일반적으로 발생하는 추가 시나리오에 대한 예제 코드를 제공합니다.

  • queue_samples_hello_world.py (비동기 버전) - 이 문서에 있는 예제:

    • 클라이언트 만들기
    • 큐 만들기
    • 메시지 보내기
    • 메시지 받기

  • queue_samples_authentication.py (비동기 버전) - 클라이언트를 인증하고 만드는 예제:

    • 연결 문자열
    • 공유 액세스 키에서
    • 공유 액세스 서명 토큰에서
    • Azure Active Directory에서

  • queue_samples_service.py (비동기 버전) - 큐 서비스와 상호 작용하기 위한 예:

    • 서비스 속성 가져오기 및 설정
    • 스토리지 계정의 큐 나열
    • 서비스에서 큐 만들기 및 삭제
    • QueueClient 가져오기

  • queue_samples_message.py (비동기 버전) - 큐 및 메시지 작업에 대한 예:

    • 액세스 정책 설정
    • 큐 메타데이터 가져오기 및 설정
    • 메시지 보내기 및 받기
    • 지정된 메시지를 삭제하고 모든 메시지 지우기
    • 메시지 Peek 및 업데이트

추가 설명서

Azure Queue Storage에 대한 보다 광범위한 설명서는 docs.microsoft.com Azure Queue Storage 설명서를 참조하세요 .

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com 을 참조하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.