Panduan Desain Bahasa Azure SDK untuk Python

Pedoman Desain Bahasa Azure SDK adalah standar komprehensif yang memastikan konsistensi, prediksi, dan kemudahan penggunaan di semua Azure SDK. Panduan ini membantu pengembang bekerja secara efisien dengan layanan Azure dengan menyediakan pola dan perilaku yang akrab di berbagai layanan dan bahasa pemrograman.

Pedoman terdiri dari dua kategori:

  • Panduan Umum: Prinsip inti yang berlaku untuk semua Azure SDK terlepas dari bahasa pemrograman.
  • Language-Specific Panduan: Detail implementasi yang dioptimalkan untuk setiap bahasa yang didukung, termasuk Python, .NET, Java, TypeScript, dan banyak lagi. Untuk informasi selengkapnya, lihat Daftar Isi yang dimulai pada halaman Panduan Umum: Pengenalan .

Panduan ini dikembangkan secara terbuka di GitHub, yang memungkinkan peninjauan dan kontribusi komunitas.

Prinsip desain umum

Semua Azure SDK mengikuti prinsip-prinsip dasar ini:

Prinsip Description
Penggunaan idiomatik SDK mengikuti konvensi dan pola khusus bahasa.
Konsistensi Perilaku seragam di berbagai layanan Azure.
Kesederhanaan Tugas umum memerlukan kode minimal.
Pengungkapan progresif Fitur tingkat lanjut tersedia tetapi tidak mempersulit penggunaan dasar.
Ketahanan Penanganan terintegrasi untuk kesalahan, coba ulang, dan pemutusan waktu.

Pedoman khusus Python

Sisa dokumen ini berfokus pada pedoman Python.

Konvensi penamaan

Azure SDK untuk Python mengikuti konvensi penamaan Python standar:

  • Metode: Gunakan snake_case.

    list_containers()
get_secret()
create_database()

  • Variabel: Gunakan snake_case.

    connection_string = "..."
retry_count = 3

  • Kelas: Gunakan PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Konstanta: Gunakan UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Struktur paket

Paket Azure SDK mengikuti struktur yang konsisten:

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

Instansiasi klien

Klien menyediakan beberapa metode instansiasi:

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 menggunakan pola autentikasi yang konsisten:

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"
)

Manajer konteks

Sebagian besar klien Azure SDK menerapkan protokol manajer konteks untuk pembersihan sumber daya otomatis:

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()

Nota

Meskipun sebagian besar klien mendukung manajer konteks, verifikasi dokumentasi klien tertentu untuk ketersediaan.

Operasi asinkron

Klien asinkron disediakan dalam modul terpisah .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())

Operasi jangka panjang

Operasi jangka panjang menggunakan awalan begin_ dan mengembalikan objek poller:

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()

Pengaturan halaman

Operasi daftar mengembalikan iterable yang menangani penomoran halaman secara otomatis:

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)

Tipe pengembalian

Metode mengembalikan objek model yang bertipe kuat daripada kamus.

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)

Penanganan kesalahan

Pengecualian Azure SDK mewarisi dari AzureError dan menyediakan jenis pengecualian tertentu:

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}")

Opsi konfigurasi

Klien menerima konfigurasi melalui argumen kata kunci:

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
)

Pola SDK umum

Hierarki klien layanan

Azure SDK biasanya mengikuti hierarki tiga tingkat:

  • Klien layanan: Titik masuk untuk operasi layanan:

    service_client = BlobServiceClient(...)

  • Klien sumber daya: Operasi pada sumber daya tertentu:

    container_client = service_client.get_container_client("container")

  • Metode operasi: Tindakan pada sumber daya:

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

Penamaan metode yang konsisten

Nama metode mengikuti pola yang dapat diprediksi:

Operasi Pola metode 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()

Bekerja dengan Azure SDK

Contoh berikut menunjukkan bagaimana panduan desain membuat konsistensi di berbagai layanan 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}")

Berkontribusi pada Azure SDK

Saat Anda memperluas atau berkontribusi pada Azure SDK:

  • Ikuti idiom Python: Gunakan pola dan konvensi Pythonic.
  • Pertahankan konsistensi: Sejajarkan dengan pola SDK yang ada.
  • Tulis pengujian komprehensif: Sertakan pengujian unit dan integrasi.
  • Dokumen secara menyeluruh: Berikan docstring dan contoh.
  • Tinjau panduan berikut: Lihat Panduan Kontribusi Azure SDK.

Berikut adalah contoh penerapan metode klien kustom yang mengikuti Panduan Desain Bahasa:

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)

Konten terkait

  • Terakhir diperbarui pada