Diretrizes de Design de Linguagem do SDK do Azure para Python

As Diretrizes de Design de Linguagens do Azure SDK são normas abrangentes que garantem consistência, previsibilidade e facilidade de utilização em todos os SDKs Azure. Essas diretrizes ajudam os desenvolvedores a trabalhar de forma eficiente com os serviços do Azure, fornecendo padrões e comportamentos familiares em diferentes serviços e linguagens de programação.

As orientações dividem-se em duas categorias:

Diretrizes Gerais: Princípios fundamentais que se aplicam a todos os SDKs do Azure, independentemente da linguagem de programação.
Language-Specific Diretrizes: Detalhes de implementação otimizados para cada linguagem suportada, incluindo Python, .NET, Java, TypeScript e muitas outras. Para mais informações, consulte o Índice a partir da página de Diretrizes Gerais: Introdução .

Estas diretrizes são desenvolvidas abertamente no GitHub, o que permite a revisão e contribuição da comunidade.

Princípios gerais de conceção

Todos os SDKs do Azure seguem estes princípios fundamentais:

Princípio	Description
Uso idiomática	Os SDKs seguem convenções e padrões específicos da linguagem.
Consistency	Os comportamentos são uniformes entre diferentes serviços Azure.
Simplicidade	Tarefas comuns requerem código mínimo.
Divulgação progressiva	Existem funcionalidades avançadas disponíveis, mas não complicam o uso básico.
Robustez	A gestão está integrada para erros, tentativas e limites de tempo.

Diretrizes específicas do Python

O resto deste documento foca-se nas diretrizes do Python.

Convenções de nomenclatura

Os SDKs do Azure para Python seguem convenções de nomenclatura Python padrão:

Métodos: Usar snake_case.

list_containers()
get_secret()
create_database()

Variáveis: Usesnake_case .

connection_string = "..."
retry_count = 3

Classes: Utilize PascalCase.

BlobServiceClient
SecretClient
CosmosClient

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

Estrutura do pacote

Os pacotes do SDK do Azure seguem uma estrutura consistente:

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

Instanciação do cliente

Os clientes fornecem vários métodos de instanciação:

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

Os SDKs do Azure usam padrões de autenticação consistentes:

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

Gestores de contexto

A maioria dos clientes do SDK do Azure implementa protocolos do gerenciador de contexto para limpeza 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()

Observação

Embora a maioria dos clientes suporte gestores de contexto, verifique a documentação específica dos clientes quanto à disponibilidade.

Operações assíncronas

Os clientes assíncronos são fornecidos em módulos separados .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())

Operações de longa duração

Operações de longa duração utilizam o prefixo begin_ e retornam objetos de polling:

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

Paginação

As operações de lista retornam iteráveis que manipulam a paginação automaticamente:

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 devolução

Os métodos retornam objetos de modelo fortemente tipados em vez de dicionários:

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)

Tratamento de erros

As exceções do Azure SDK herdam de AzureError e fornecem tipos específicos de exceção.

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

Opções de configuração

Os clientes aceitam a configuração através de argumentos de palavra-chave:

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
)

Padrões comuns do SDK

Hierarquia do cliente de serviço

Os SDKs do Azure normalmente seguem uma hierarquia de três níveis:

Cliente de serviço: Ponto de entrada para operações de serviço:
```
service_client = BlobServiceClient(...)
```

Cliente de recursos: Operações em recursos específicos:

container_client = service_client.get_container_client("container")

Métodos de operação: Ações sobre recursos:

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

Nomenclatura consistente do método

Os nomes dos métodos seguem padrões previsíveis:

Funcionamento	Padrão de método	Example
Criar	`create_<resource>`	`create_container()`
Leitura	`get_<resource>`	`get_blob()`
Atualização	`update_<resource>`	`update_secret()`
Delete	`delete_<resource>`	`delete_container()`
List	`list_<resources>`	`list_blobs()`
Exists	`exists()`	`blob_client.exists()`

Trabalhar com Azure SDKs

O exemplo a seguir demonstra como as diretrizes de design criam consistência entre diferentes serviços do 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}")

Contribuir para os SDKs do Azure

Quando estende ou contribui para SDKs do Azure:

Siga os idiomas Python: Usa padrões e convenções Pythonic.
Mantenha a consistência: Alinhe-se com os padrões existentes do SDK.
Escreva testes abrangentes: Inclua testes unitários e de integração.
Documente minuciosamente: Forneça docstrings e exemplos.
Diretrizes de revisão: Consulte o Guia de Contribuições do Azure SDK.

Aqui está um exemplo de implementação de um método cliente personalizado que segue as Diretrizes de Design de Linguagem:

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)

Consulte as Diretrizes de Design do Azure SDK completas.
Leia a página de Lançamentos do Azure SDK.

Comentários

Esta página foi útil?

Última atualização a 2025-12-09