Az Azure SDK nyelvi tervezési irányelvei a Pythonhoz

Az Azure SDK nyelvi tervezési irányelvei átfogó szabványok, amelyek minden Azure SDK-ban biztosítják a konzisztenciát, a kiszámíthatóságot és a könnyű használatot. Ezek az irányelvek segítenek a fejlesztőknek hatékonyan együttműködni az Azure-szolgáltatásokkal azáltal, hogy ismerős mintákat és viselkedéseket biztosítanak a különböző szolgáltatások és programozási nyelvek között.

Az irányelvek két kategóriából állnak:

  • Általános irányelvek: Az összes Azure SDK-ra vonatkozó alapelvek a programozási nyelvtől függetlenül.
  • Language-Specific irányelvek: Az egyes támogatott nyelvekre optimalizált implementáció részletei, beleértve a Pythont, a .NET-et, a Java-t, a TypeScriptet és még sok mást. További információkért tekintse meg a Tartalomjegyzéket az Általános irányelvek: Bevezetés oldalon.

Ezeket az irányelveket nyíltan a GitHubon dolgozták ki, amely lehetővé teszi a közösségi felülvizsgálatot és közreműködést.

Általános tervezési alapelvek

Minden Azure SDK az alábbi alapelveket követi:

Elv Description
Idiomatikus használat Az SDK-k nyelvspecifikus konvenciókat és mintákat követnek.
Consistency A viselkedések egységesek a különböző Azure-szolgáltatásokban.
Egyszerűség A gyakori feladatokhoz minimális kód szükséges.
Fokozatos közzététel Speciális funkciók érhetők el, de nem bonyolítják az alapszintű használatot.
Erőteljesség A hibakezelés, újrapróbálkozás és időtúllépés kezelése be van építve.

Python-specifikus irányelvek

A dokumentum többi része a Python-irányelvekre összpontosít.

Elnevezési konvenciók

A Pythonhoz készült Azure SDK-k a Python szokásos elnevezési konvencióit követik:

  • Metódusok: Használja snake_case.

    list_containers()
get_secret()
create_database()

  • Változók: Használja snake_case.

    connection_string = "..."
retry_count = 3

  • Osztályok: Használja PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Állandók: Használja UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Csomagstruktúra

Az Azure SDK-csomagok egységes struktúrát követnek:

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

Ügyfél példányosítása

Az ügyfelek több példányosítási módszert is biztosítanak:

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

Az Azure SDK-k konzisztens hitelesítési mintákat használnak:

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

Környezetkezelők

A legtöbb Azure SDK-ügyfél környezetkezelő protokollokat implementál az automatikus erőforrás-törléshez:

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

Megjegyzés:

Bár a legtöbb ügyfél támogatja a környezetmenedzsereket, ellenőrizze a rendelkezésre állás konkrét ügyféldokumentációját.

Aszinkron műveletek

Az Async-ügyfelek külön .aio modulokban érhetők el:

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

Hosszú ideig futó műveletek

A hosszan futó műveletek a begin_ előtagot használják, és poller objektumokat adnak vissza.

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

Oldalszámozás

A listaműveletek olyan iterációkat adnak vissza, amelyek automatikusan kezelik a lapozást:

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)

Visszatérési típusok

A metódusok szótárak helyett erősen gépelt modellobjektumokat ad vissza:

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)

Hibakezelés

Az Azure SDK-kivételek AzureError osztályból származnak, és speciális kivételtípusokat biztosítanak.

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

Konfigurációs lehetőségek

Az ügyfelek kulcsszóargumentumokkal fogadják el a konfigurációt:

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
)

Gyakori SDK-minták

Szolgáltatásügyfél-hierarchia

Az Azure SDK-k általában háromszintű hierarchiát követnek:

  • Szolgáltatásügyfél: Belépési pont a szolgáltatásműveletekhez:

    service_client = BlobServiceClient(...)

  • Erőforrás-ügyfél: Műveletek adott erőforrásokon:

    container_client = service_client.get_container_client("container")

  • Műveleti módszerek: Erőforrásokon végzett műveletek:

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

Konzisztens metódus elnevezése

A metódusnevek kiszámítható mintákat követnek:

Operation Metódusminta Example
Create create_<resource> create_container()
Olvasás get_<resource> get_blob()
Update update_<resource> update_secret()
Delete delete_<resource> delete_container()
List list_<resources> list_blobs()
Exists exists() blob_client.exists()

Az Azure SDK-k használata

Az alábbi példa bemutatja, hogyan hozzák létre a tervezési irányelvek a különböző Azure-szolgáltatások konzisztenciáját:

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

Közreműködés az Azure SDK-kban

Az Azure SDK-k kiterjesztésekor vagy közreműködése esetén:

  • Kövesse a Python-kifejezéseket: Python-mintákat és konvenciókat használjon.
  • Konzisztencia fenntartása: Igazodjon a meglévő SDK-mintákhoz.
  • Átfogó tesztek írása: Egység- és integrációs tesztek belefoglalása.
  • Dokumentáljon alaposan: Adjon meg docstringeket és példákat.
  • Útmutatók áttekintése: Tekintse meg az Azure SDK közreműködési útmutatóját.

Íme egy példa egy egyéni ügyfélmetódus implementálására, amely a nyelvi tervezési útmutatót követi:

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)

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: