Linee guida per la progettazione del linguaggio di Azure SDK per Python

Le linee guida per la progettazione del linguaggio di Azure SDK sono standard completi che garantiscono coerenza, prevedibilità e facilità d'uso in tutti gli SDK di Azure. Queste linee guida consentono agli sviluppatori di lavorare in modo efficiente con i servizi di Azure fornendo modelli e comportamenti familiari in diversi servizi e linguaggi di programmazione.

Le linee guida sono costituite da due categorie:

  • Linee guida generali: principi di base applicabili a tutti gli SDK di Azure indipendentemente dal linguaggio di programmazione.
  • linee guidaLanguage-Specific: dettagli di implementazione ottimizzati per ogni linguaggio supportato, tra cui Python, .NET, Java, TypeScript e molti altri ancora. Per altre informazioni, vedere sommario a partire dalla pagina Linee guida generali: Introduzione .

Queste linee guida vengono sviluppate apertamente su GitHub, che consente la revisione e il contributo della community.

Principi di progettazione generali

Tutti gli SDK di Azure seguono questi principi fondamentali:

Principio Description
Utilizzo idiotico Gli SDK seguono convenzioni e modelli specifici del linguaggio.
Coerenza I comportamenti sono uniformi in diversi servizi di Azure.
Semplicità Le attività comuni richiedono codice minimo.
Divulgazione progressiva Le funzionalità avanzate sono disponibili, ma non complicano l'utilizzo di base.
Robustezza La gestione è incorporata per errori, ritentativi e timeout.

Linee guida specifiche di Python

Il resto di questo documento è incentrato sulle linee guida di Python.

Convenzioni di denominazione

Gli SDK di Azure per Python seguono le convenzioni di denominazione Standard di Python:

  • Metodi: usare snake_case.

    list_containers()
get_secret()
create_database()

  • Variabili: usare snake_case.

    connection_string = "..."
retry_count = 3

  • Classi: usare PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Costanti: usare UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Struttura del pacchetto

I pacchetti di Azure SDK seguono una struttura coerente:

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

Creazione di istanze client

I client forniscono più metodi di creazione di istanze:

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

Gli SDK di Azure usano modelli di autenticazione coerenti:

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

Gestioni contesti

La maggior parte dei client Azure SDK implementa protocolli di gestione del contesto per la pulizia automatica delle risorse:

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

Annotazioni

Anche se la maggior parte dei client supporta i gestori di contesto, verificare la documentazione specifica del client per la disponibilità.

Operazioni asincrone

I client asincroni vengono forniti in moduli separati .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())

Operazioni a esecuzione prolungata

Le operazioni a esecuzione prolungata usano il prefisso begin_ e restituiscono oggetti 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()

Impaginazione

Le operazioni di elenco restituiscono iterabili che gestiscono automaticamente la paginazione:

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)

Tipi restituiti

I metodi restituiscono oggetti modello fortemente tipizzati anziché dizionari:

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)

Gestione degli errori

Le eccezioni di Azure SDK ereditano da AzureError e forniscono tipi di eccezione specifici:

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

Opzioni di configurazione

I client accettano la configurazione tramite argomenti di parole chiave:

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
)

Modelli SDK comuni

Gerarchia client del servizio

Gli SDK di Azure seguono in genere una gerarchia a tre livelli:

  • Client del servizio: punto di ingresso per operazioni di servizio:

    service_client = BlobServiceClient(...)

  • Client delle risorse: Operazioni su risorse specifiche:

    container_client = service_client.get_container_client("container")

  • Metodi operativi: azioni sulle risorse:

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

Denominazione coerente dei metodi

I nomi dei metodi seguono modelli prevedibili:

Operation Modello di metodo Example
Creazione create_<resource> create_container()
Leggi get_<resource> get_blob()
Update update_<resource> update_secret()
Delete delete_<resource> delete_container()
Elenco list_<resources> list_blobs()
Exists exists() blob_client.exists()

Usare gli SDK di Azure

L'esempio seguente illustra come le linee guida di progettazione creano coerenza tra diversi servizi di 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}")

Contribuire agli SDK di Azure

Quando si estende o si contribuisce agli SDK di Azure:

  • Seguire i linguaggi Python: Usare modelli e convenzioni pythonici.
  • Mantenere la coerenza: Allinearsi ai modelli SDK esistenti.
  • Scrivere test completi: Includere i test unitari e i test di integrazione.
  • Documentare in modo completo: Fornisci docstring ed esempi.
  • Rivedere le linee guida: Consultare la Guida ai contributi di Azure SDK.

Ecco un esempio di implementazione di un metodo client personalizzato che segue le linee guida per la progettazione del linguaggio:

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)

Contenuti correlati

  • Ultimo aggiornamento: