Compartilhar via


Biblioteca de clientes compartilhados do Azure Core para Python – versão 1.29.6

O Azure Core fornece exceções e módulos compartilhados para bibliotecas de clientes do SDK do Python. Essas bibliotecas seguem as Diretrizes de Design do SDK do Azure para Python .

Se você for um desenvolvedor de biblioteca de clientes, consulte a referência de desenvolvedor da biblioteca de clientes para obter mais informações.

Código-fonte | Pacote (Pypi) | Pacote (Conda) | Documentação de referência da API

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e tirar dúvidas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Normalmente, você não precisará instalar o azure core; ele será instalado quando você instalar uma das bibliotecas de cliente usando-a. Caso deseje instalá-lo explicitamente (para implementar sua própria biblioteca de clientes, por exemplo), você pode encontrá-la aqui.

Principais conceitos

Exceções da Biblioteca Principal do Azure

AzureError

AzureError é a exceção base para todos os erros.

class AzureError(Exception):
    def __init__(self, message, *args, **kwargs):
        self.inner_exception = kwargs.get("error")
        self.exc_type, self.exc_value, self.exc_traceback = sys.exc_info()
        self.exc_type = self.exc_type.__name__ if self.exc_type else type(self.inner_exception)
        self.exc_msg = "{}, {}: {}".format(message, self.exc_type, self.exc_value)  # type: ignore
        self.message = str(message)
        self.continuation_token = kwargs.get("continuation_token")
        super(AzureError, self).__init__(self.message, *args)

message é qualquer mensagem (str) a ser associada à exceção.

args são quaisquer argumentos adicionais a serem incluídos com exceção.

Kwargs são palavra-chave argumentos a serem incluídos com a exceção. Use o erro palavra-chave para passar uma exceção interna e continuation_token para que uma referência de token continue uma operação incompleta.

As seguintes exceções herdam do AzureError:

ServiceRequestError

Ocorreu um erro durante a tentativa de fazer uma solicitação ao serviço. Nenhuma solicitação foi enviada.

ServiceResponseError

A solicitação foi enviada, mas o cliente não entendeu a resposta. A conexão pode ter esgotado. Esses erros podem ser repetidos para operações idempotentes ou seguras.

HttpResponseError

Uma solicitação foi feita e um código de status sem êxito foi recebido do serviço.

class HttpResponseError(AzureError):
    def __init__(self, message=None, response=None, **kwargs):
        self.reason = None
        self.response = response
        if response:
            self.reason = response.reason
            self.status_code = response.status_code
        self.error = self._parse_odata_body(ODataV4Format, response)  # type: Optional[ODataV4Format]
        if self.error:
            message = str(self.error)
        else:
            message = message or "Operation returned an invalid status '{}'".format(
                self.reason
            )

        super(HttpResponseError, self).__init__(message=message, **kwargs)

message é a mensagem de erro de resposta HTTP (opcional)

response é a resposta HTTP (opcional).

Kwargs são palavra-chave argumentos a serem incluídos com a exceção.

As seguintes exceções herdam de HttpResponseError:

DecodeError

Um erro gerado durante a desserialização da resposta.

IncompleteReadError

Um erro gerado se o par fechar a conexão antes de recebermos o corpo completo da mensagem.

ResourceExistsError

Uma resposta de erro com status código 4xx. Isso não será gerado diretamente pelo pipeline principal do Azure.

ResourceNotFoundError

Uma resposta de erro, normalmente disparada por uma resposta 412 (para atualização) ou 404 (para obter/postar).

ResourceModifiedError

Uma resposta de erro com status código 4xx, normalmente 412 Conflitos. Isso não será gerado diretamente pelo pipeline principal do Azure.

ResourceNotModifiedError

Uma resposta de erro com status código 304. Isso não será gerado diretamente pelo pipeline principal do Azure.

ClientAuthenticationError

Uma resposta de erro com status código 4xx. Isso não será gerado diretamente pelo pipeline principal do Azure.

TooManyRedirectsError

Um erro gerado quando o número máximo de tentativas de redirecionamento é atingido. A quantidade máxima de redirecionamentos pode ser configurada na RedirectPolicy.

class TooManyRedirectsError(HttpResponseError):
    def __init__(self, history, *args, **kwargs):
        self.history = history
        message = "Reached maximum redirect attempts."
        super(TooManyRedirectsError, self).__init__(message, *args, **kwargs)

O histórico é usado para documentar as solicitações/respostas que resultaram em solicitações redirecionadas.

args são quaisquer argumentos adicionais a serem incluídos com exceção.

Kwargs são palavra-chave argumentos a serem incluídos com a exceção.

StreamConsumedError

Um erro gerado se você tentar acessar o fluxo de ou azure.core.rest.AsyncHttpResponse depois que o fluxo de azure.core.rest.HttpResponse resposta tiver sido consumido.

StreamClosedError

Um erro gerado se você tentar acessar o fluxo do ou azure.core.rest.AsyncHttpResponse depois que o fluxo de azure.core.rest.HttpResponse resposta for fechado.

ResponseNotReadError

Um erro gerado se você tentar acessar o content de ou azure.core.rest.AsyncHttpResponse antes de azure.core.rest.HttpResponse ler os bytes da resposta primeiro.

Configurações

Ao chamar os métodos, algumas propriedades podem ser configuradas passando como argumentos kwargs.

Parâmetros Descrição
headers Os cabeçalhos de Solicitação HTTP.
request_id A ID da solicitação a ser adicionada ao cabeçalho.
user_agent Se especificado, isso será adicionado na frente da cadeia de caracteres do agente do usuário.
logging_enable Use para habilitar por operação. Assume o padrão de False.
agente Se especificado, ele será usado para registrar informações em log.
response_encoding A codificação a ser usada se conhecida para esse serviço (desabilitará a detecção automática).
proxies Mapeia protocolo ou protocolo e nome do host para a URL do proxy.
raw_request_hook Função de retorno de chamada. Será invocado na solicitação.
raw_response_hook Função de retorno de chamada. Será invocado na resposta.
network_span_namer Um que pode ser chamado para personalizar o nome do intervalo.
tracing_attributes Atributos a serem definidos em todos os intervalos criados.
permit_redirects Se o cliente permite redirecionamentos. Assume o padrão de True.
redirect_max O máximo de redirecionamentos permitidos. Assume o padrão de 30.
retry_total Número total de tentativas a serem permitidas. Tem precedência sobre outras contagens. O valor padrão é 10.
retry_connect Quantos erros relacionados à conexão tentar novamente. Esses são erros gerados antes que a solicitação seja enviada ao servidor remoto, que presumimos não ter disparado o servidor para processar a solicitação. O valor padrão é 3.
retry_read Quantas vezes tentar novamente em erros de leitura. Esses erros são gerados depois que a solicitação foi enviada ao servidor, portanto, a solicitação pode ter efeitos colaterais. O valor padrão é 3.
retry_status Quantas vezes tentar novamente em códigos de status inválidos. O valor padrão é 3.
retry_backoff_factor Um fator de retirada a ser aplicado entre tentativas após a segunda tentativa (a maioria dos erros é resolvida imediatamente por uma segunda tentativa sem atraso). A política de repetição ficará em suspensão por: {backoff factor} * (2 ** ({number of total retries} - 1)) segundos. Se o backoff_factor for 0,1, a repetição será suspensa para [0.0s, 0.2s, 0.4s, ...] entre as repetições. O valor padrão é 0.8.
retry_backoff_max O tempo máximo de retirada. O valor padrão é 120 segundos (2 minutos).
retry_mode Corrigido ou atraso exponencial entre tentativas, o padrão é Exponential.
tempo limite Configuração de tempo limite para a operação em segundos, o padrão é 604800s (7 dias).
connection_timeout Um único float em segundos para o tempo limite da conexão. O padrão é 300 segundos.
read_timeout Um único float em segundos para o tempo limite de leitura. O padrão é 300 segundos.
connection_verify Verificação de certificado SSL. Habilitado por padrão. Defina como False para desabilitar, como alternativa, pode ser definido como o caminho para um arquivo ou diretório CA_BUNDLE com certificados de ACs confiáveis.
connection_cert Certificados do lado do cliente. Você pode especificar um certificado local para usar como certificado do lado do cliente, como um único arquivo (contendo a chave privada e o certificado) ou como uma tupla dos caminhos de ambos os arquivos.
proxies Protocolo de mapeamento de dicionário ou protocolo e nome do host para a URL do proxy.
cookies Objeto Dict ou CookieJar a ser enviado com o Request.
connection_data_block_size O tamanho do bloco de dados enviados pela conexão. O padrão é 4096 bytes.

Transporte assíncrono

O transporte assíncrono foi projetado para ser aceito. O AioHttp é uma das implementações com suporte do transporte assíncrono. Ele não está instalado por padrão. Você precisa instalá-lo separadamente.

Módulos compartilhados

MatchConditions

MatchConditions é uma enumeração para descrever as condições de correspondência.

class MatchConditions(Enum):
    Unconditionally = 1  # Matches any condition
    IfNotModified = 2  # If the target object is not modified. Usually it maps to etag=<specific etag>
    IfModified = 3  # Only if the target object is modified. Usually it maps to etag!=<specific etag>
    IfPresent = 4   # If the target object exists. Usually it maps to etag='*'
    IfMissing = 5   # If the target object does not exist. Usually it maps to etag!='*'

CaseInsensitiveEnumMeta

Uma metaclasse para dar suporte a enumerações que não diferenciam maiúsculas de minúsculas.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

class MyCustomEnum(str, Enum, metaclass=CaseInsensitiveEnumMeta):
    FOO = 'foo'
    BAR = 'bar'

Valor do Sentinel nulo

Um objeto sentinela falso que deve ser usado para especificar atributos sem dados. Isso é serializado para null no fio.

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.