Python용 Azure SDK 언어 디자인 지침

Azure SDK 언어 디자인 지침은 모든 Azure SDK에서 일관성, 예측 가능성 및 사용 편의성을 보장하는 포괄적인 표준입니다. 이러한 지침은 개발자가 다양한 서비스 및 프로그래밍 언어에서 친숙한 패턴과 동작을 제공하여 Azure 서비스를 효율적으로 작업하는 데 도움이 됩니다.

지침은 다음 두 가지 범주로 구성됩니다.

일반 지침: 프로그래밍 언어에 관계없이 모든 Azure SDK에 적용되는 핵심 원칙입니다.
Language-Specific 지침: Python, .NET, Java, TypeScript 등을 포함하여 지원되는 각 언어에 최적화된 구현 세부 정보입니다. 자세한 내용은 일반 지침: 소개 페이지에서 시작하는 목차를 참조하세요.

이러한 지침은 커뮤니티 검토 및 기여를 허용하는 GitHub에서 공개적으로 개발됩니다.

일반 디자인 원칙

모든 Azure SDK는 다음 기본 원칙을 따릅니다.

원리	Description
Idiomatic 사용량	SDK는 언어별 규칙 및 패턴을 따릅니다.
일관성	동작은 여러 Azure 서비스에서 균일합니다.
단순	일반적인 작업에는 최소한의 코드가 필요합니다.
점진적 공개	고급 기능을 사용할 수 있지만 기본 사용을 복잡하게 만들지는 않습니다.
견고성	오류, 재시도 및 시간 제한에 대한 처리가 기본 제공됩니다.

Python 관련 지침

이 문서의 나머지 내용은 Python 지침에 중점을 둡니다.

명명 규칙

Python용 Azure SDK는 표준 Python 명명 규칙을 따릅니다.

메서드: 사용 snake_case.

list_containers()
get_secret()
create_database()

변수: 사용 snake_case.

connection_string = "..."
retry_count = 3

클래스: 사용 PascalCase.

BlobServiceClient
SecretClient
CosmosClient

상수: 사용 UPPER_CASE.
```
DEFAULT_CHUNK_SIZE
MAX_RETRIES
```

패키지 구조

Azure SDK 패키지는 일관된 구조를 따릅니다.

azure-<service>-<feature>
├── azure/
│   └── <service>/
│       ├── __init__.py
│       ├── _client.py
│       ├── _models.py
│       └── aio/           # Async implementations
│           └── __init__.py

클라이언트 인스턴스화

클라이언트는 다음과 같은 여러 인스턴스화 메서드를 제공합니다.

from azure.storage.blob import BlobServiceClient
from azure.identity import DefaultAzureCredential

# Note: Do not use connection string if you can possibly avoid it!

# Using account URL and credential
credential = DefaultAzureCredential()
client = BlobServiceClient(account_url="https://account.blob.core.windows.net", 
                          credential=credential)

Authentication

Azure SDK는 일관된 인증 패턴을 사용합니다.

from azure.identity import DefaultAzureCredential, ClientSecretCredential

# Default credential chain
credential = DefaultAzureCredential()

# Explicit credential
credential = ClientSecretCredential(
    tenant_id="tenant-id",
    client_id="client-id",
    client_secret="secret"
)

컨텍스트 관리자

대부분의 Azure SDK 클라이언트는 자동 리소스 정리를 위해 컨텍스트 관리자 프로토콜을 구현합니다.

from azure.storage.blob import BlobServiceClient

# Automatic cleanup with context manager
with BlobServiceClient.from_connection_string(conn_str) as client:
    container_client = client.get_container_client("mycontainer")
    blob_list = container_client.list_blobs()

비고

대부분의 클라이언트는 컨텍스트 관리자를 지원하지만 가용성에 대한 특정 클라이언트 설명서를 확인합니다.

비동기 작업

비동기 클라이언트는 별도의 .aio 모듈에서 제공됩니다.

from azure.storage.blob.aio import BlobServiceClient
import asyncio

async def list_blobs_async():
    async with BlobServiceClient.from_connection_string(conn_str) as client:
        container_client = client.get_container_client("mycontainer")
        async for blob in container_client.list_blobs():
            print(blob.name)

# Run async function
asyncio.run(list_blobs_async())

장기 실행 작업

장기 실행 작업은 접두사 begin_를 사용하며 폴러 객체를 반환합니다.

from azure.storage.blob import BlobServiceClient

client = BlobServiceClient.from_connection_string(conn_str)
container_client = client.get_container_client("mycontainer")

# Start long-running operation
poller = container_client.begin_copy_blob_from_url(source_url)

# Wait for completion
result = poller.result()

# Or check status
if poller.done():
    result = poller.result()

Pagination

목록 작업은 페이지 매김을 자동으로 처리하는 반복 가능 개체를 반환합니다.

from azure.storage.blob import BlobServiceClient

client = BlobServiceClient.from_connection_string(conn_str)

# Automatic pagination
for container in client.list_containers():
    print(container.name)

# Manual pagination control
containers = client.list_containers(results_per_page=10).by_page()
for page in containers:
    for container in page:
        print(container.name)

반환 형식

메서드는 사전이 아닌 강력한 형식의 모델 개체를 반환합니다.

from azure.keyvault.secrets import SecretClient

client = SecretClient(vault_url="...", credential=credential)

# Returns KeyVaultSecret object, not dict
secret = client.get_secret("my-secret")
print(secret.value)
print(secret.properties.created_on)

오류 처리

Azure SDK 예외는 AzureError을 상속받고 특정 예외 유형을 제공합니다.

from azure.core.exceptions import (
    AzureError,
    ResourceNotFoundError,
    ResourceExistsError,
    ClientAuthenticationError,
    HttpResponseError
)

try:
    blob_client.download_blob()
except ResourceNotFoundError:
    # Handle missing resource
    print("Blob not found")
except ClientAuthenticationError:
    # Handle authentication failure
    print("Authentication failed")
except HttpResponseError as e:
    # Handle HTTP errors
    print(f"HTTP {e.status_code}: {e.message}")
except AzureError as e:
    # Handle any other Azure SDK error
    print(f"Azure SDK error: {e}")

구성 옵션

클라이언트는 키워드 인수를 통해 구성을 수락합니다.

from azure.storage.blob import BlobServiceClient

client = BlobServiceClient(
    account_url="...",
    credential=credential,
    # Configuration options
    max_single_put_size=64 * 1024 * 1024,
    max_block_size=4 * 1024 * 1024,
    retry_total=3,
    logging_enable=True
)

일반적인 SDK 패턴

서비스 클라이언트 계층 구조

Azure SDK는 일반적으로 3단계 계층 구조를 따릅니다.

서비스 클라이언트: 서비스 작업의 진입점:
```
service_client = BlobServiceClient(...)
```

리소스 클라이언트: 특정 리소스에 대한 작업:

container_client = service_client.get_container_client("container")

작업 방법: 리소스에 대한 작업:

blob_client = container_client.get_blob_client("blob.txt")
blob_client.upload_blob(data)

일관된 메서드 이름 지정

메서드 이름은 예측 가능한 패턴을 따릅니다.

수술	메서드 패턴	Example
Create	`create_<resource>`	`create_container()`
Read	`get_<resource>`	`get_blob()`
Update	`update_<resource>`	`update_secret()`
Delete	`delete_<resource>`	`delete_container()`
List	`list_<resources>`	`list_blobs()`
Exists	`exists()`	`blob_client.exists()`

Azure SDK와 함께 작업하기

다음 예제에서는 디자인 지침이 여러 Azure 서비스에서 일관성을 만드는 방법을 보여 줍니다.

from azure.storage.blob import BlobServiceClient
from azure.keyvault.secrets import SecretClient
from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

# Consistent authentication
credential = DefaultAzureCredential()

# Consistent client instantiation
blob_service = BlobServiceClient(
    account_url="https://account.blob.core.windows.net",
    credential=credential
)
secret_client = SecretClient(
    vault_url="https://vault.vault.azure.net",
    credential=credential
)
cosmos_client = CosmosClient(
    url="https://account.documents.azure.com",
    credential=credential
)

# Consistent method patterns
containers = blob_service.list_containers()
secrets = secret_client.list_properties_of_secrets()
databases = cosmos_client.list_databases()

# Consistent error handling
from azure.core.exceptions import ResourceNotFoundError

try:
    blob_service.get_container_client("container").get_container_properties()
    secret_client.get_secret("secret")
    cosmos_client.get_database_client("database").read()
except ResourceNotFoundError as e:
    print(f"Resource not found: {e}")

Azure SDK에 기여

Azure SDK를 확장하거나 기여하는 경우:

Python 관용구를 따릅니다. Python 패턴 및 규칙을 사용합니다.
일관성 유지 관리: 기존 SDK 패턴에 맞춥니다.
포괄적인 테스트를 작성합니다. 단위 및 통합 테스트를 포함합니다.
철저하게 문서화: 문서 문자열 및 예제를 제공합니다.
검토 지침: Azure SDK 기여 가이드를 참조하세요.

다음은 언어 디자인 지침을 따르는 사용자 지정 클라이언트 메서드를 구현하는 예제입니다.

def list_items_with_prefix(self, prefix: str, **kwargs) -> ItemPaged[ItemProperties]:
    """List items that start with the specified prefix.
    
    :param str prefix: The prefix to filter items
    :return: An iterable of ItemProperties
    :rtype: ~azure.core.paging.ItemPaged[ItemProperties]
    
    :example:
        items = client.list_items_with_prefix("test-")
        for item in items:
            print(item.name)
    """
    return self.list_items(name_starts_with=prefix, **kwargs)

피드백

이 페이지가 도움이 되었나요?

2025-12-09 에 마지막으로 업데이트됨