Directrices de diseño de lenguaje del SDK de Azure para Python

Las directrices de diseño de lenguaje del SDK de Azure son estándares completos que garantizan la coherencia, la previsibilidad y la facilidad de uso en todos los SDK de Azure. Estas directrices ayudan a los desarrolladores a trabajar de forma eficaz con los servicios de Azure proporcionando patrones y comportamientos conocidos en distintos servicios y lenguajes de programación.

Las directrices constan de dos categorías:

Directrices generales: principios básicos que se aplican a todos los SDK de Azure independientemente del lenguaje de programación.
Language-Specific Directrices: detalles de implementación optimizados para cada lenguaje compatible, como Python, .NET, Java, TypeScript y muchos más. Para obtener más información, vea la tabla de contenido a partir de la página Directrices generales: Introducción .

Estas directrices se desarrollan abiertamente en GitHub, lo que permite la revisión y contribución de la comunidad.

Principios generales de diseño

Todos los SDK de Azure siguen estos principios fundamentales:

Principio	Description
Uso idiomático	Los SDK siguen convenciones y patrones específicos del lenguaje.
Uniformidad	Los comportamientos son uniformes en distintos servicios de Azure.
Simplicidad	Las tareas comunes requieren código mínimo.
Divulgación progresiva	Las características avanzadas están disponibles, pero no complican el uso básico.
Robustez	La gestión de errores, intentos adicionales y tiempos de espera está integrada.

Directrices específicas de Python

El resto de este documento se centra en las directrices de Python.

Convenciones de nomenclatura

Los SDK de Azure para Python siguen las convenciones de nomenclatura estándar de Python:

Métodos: use snake_case.

list_containers()
get_secret()
create_database()

Variables: use snake_case.

connection_string = "..."
retry_count = 3

Clases: use PascalCase.

BlobServiceClient
SecretClient
CosmosClient

Constantes: Use UPPER_CASE.
```
DEFAULT_CHUNK_SIZE
MAX_RETRIES
```

Estructura del paquete

Los paquetes del SDK de Azure siguen una estructura coherente:

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

Creación de instancias de cliente

Los clientes proporcionan varios métodos de creación de instancias:

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)

Autenticación

Los SDK de Azure usan patrones de autenticación coherentes:

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

Administradores de contexto

La mayoría de los clientes del SDK de Azure implementan protocolos de administrador de contexto para la limpieza automática de recursos:

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:

Aunque la mayoría de los clientes admiten administradores de contexto, compruebe la documentación específica del cliente para obtener disponibilidad.

Operaciones asincrónicas

Los clientes asincrónicos se proporcionan en módulos independientes .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())

Operaciones de larga duración

Las operaciones de ejecución prolongada usan el begin_ prefijo y devuelven objetos de sondeo:

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

Paginación

Las operaciones de lista devuelven iterables que controlan la paginación automáticamente:

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)

Tipos de retorno

Los métodos devuelven objetos de modelo fuertemente tipados en lugar de diccionarios:

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)

Control de errores

Las excepciones del SDK de Azure heredan de AzureError y proporcionan tipos de excepciones específicos:

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

Opciones de configuración

Los clientes aceptan la configuración mediante argumentos de palabra clave:

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
)

Patrones comunes del SDK

Jerarquía de cliente de servicio

Los SDK de Azure suelen seguir una jerarquía de tres niveles:

Cliente de servicio: punto de entrada para las operaciones de servicio:
```
service_client = BlobServiceClient(...)
```

Cliente de recursos: operaciones en recursos específicos:

container_client = service_client.get_container_client("container")

Métodos de operación: Acciones en recursos:

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

Nomenclatura de método coherente

Los nombres de método siguen patrones de predicción:

Operation	Patrón de método	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()`

Uso de SDK de Azure

En el ejemplo siguiente se muestra cómo las directrices de diseño crean coherencia en distintos servicios de 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}")

Contribución a los SDK de Azure

Al ampliar o contribuir a los SDK de Azure:

Siga los modismos de Python: Utilice patrones y convenciones Pythonicas.
Mantener la coherencia: Alinee con los patrones de SDK existentes.
Escribir pruebas completas: Incluya pruebas unitarias e de integración.
Documente exhaustivamente: Proporcione docstrings y ejemplos.
Directrices de revisión: Consulte la Guía de contribución del SDK de Azure.

Este es un ejemplo de implementación de un método de cliente personalizado que sigue las Directrices de diseño de lenguaje:

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)

Revise las directrices de diseño completas del SDK de Azure.
Consulte la página Versiones del SDK de Azure.

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2025-12-09