Biblioteca de cliente partilhada do Azure Core para Python – versão 1.29.6

O Azure Core fornece exceções e módulos partilhados para bibliotecas de cliente do SDK Python. Estas bibliotecas seguem as Diretrizes de Estrutura do SDK do Azure para Python .

Se for um programador de bibliotecas de cliente, consulte a referência do programador da biblioteca de cliente para obter mais informações.

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

Exclusão de Responsabilidade

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

Introdução

Normalmente, não terá de instalar o azure core; será instalado quando instalar uma das bibliotecas de cliente que a utiliza. Caso pretenda instalá-la explicitamente (para implementar a sua própria biblioteca de cliente, por exemplo), pode encontrá-la aqui.

Conceitos-chave

Exceções da Biblioteca principal do Azure

AzureError

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

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

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

os kwargs são argumentos de palavra-chave a incluir com a exceção. Utilize o erro de palavra-chave para transmitir uma exceção interna e continuation_token para uma referência de token para continuar uma operação incompleta.

As seguintes exceções herdam do AzureError:

ServiceRequestError

Ocorreu um erro ao tentar fazer um pedido ao serviço. Não foi enviado nenhum pedido.

ServiceResponseError

O pedido foi enviado, mas o cliente não conseguiu compreender a resposta. A ligação pode ter excedido o tempo limite. Estes erros podem ser repetidos para operações idempotentes ou seguras.

HttpResponseError

Foi feito um pedido e foi recebido um código de estado sem êxito 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)

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

a resposta é a resposta HTTP (opcional).

os kwargs são argumentos de palavra-chave a incluir com a exceção.

As seguintes exceções herdam de HttpResponseError:

DecodeError

Um erro gerado durante a des serialização da resposta.

IncompleteReadError

Foi gerado um erro se o elemento da rede fechar a ligação antes de recebermos o corpo completo da mensagem.

ResourceExistsError

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

ResourceNotFoundError

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

ResourceModifiedError

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

ResourceNotModifiedError

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

ClientAuthenticationError

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

TooManyRedirectsError

Ocorreu um erro quando é atingido o número máximo de tentativas de redirecionamento. A quantidade máxima de redirecionamentos pode ser configurada no 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 é utilizado para documentar os pedidos/respostas que resultaram em pedidos redirecionados.

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

os kwargs são argumentos de palavra-chave a incluir com a exceção.

StreamConsumedError

Foi emitido um erro se tentar aceder ao fluxo de ou azure.core.rest.AsyncHttpResponse depois de o fluxo de azure.core.rest.HttpResponse resposta ter sido consumido.

StreamClosedError

Foi emitido um erro se tentar aceder ao fluxo do ou azure.core.rest.AsyncHttpResponse após o fluxo de azure.core.rest.HttpResponse resposta ter sido fechado.

ResponseNotReadError

Foi emitido um erro se tentar aceder primeiro aos content bytes de ou azure.core.rest.AsyncHttpResponse antes de azure.core.rest.HttpResponse ler nos bytes da resposta.

Configurações

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

Parâmetros	Description
cabeçalhos	Os cabeçalhos do Pedido HTTP.
request_id	O ID do pedido a adicionar ao cabeçalho.
user_agent	Se for especificado, este procedimento será adicionado à frente da cadeia de agente do utilizador.
logging_enable	Utilize para ativar por operação. Predefinições para False.
logger	Se especificado, será utilizado para registar informações.
response_encoding	A codificação a utilizar se for conhecida por este serviço (irá desativar a deteção automática).
Proxies	Mapeia o protocolo ou o protocolo e o nome do anfitrião para o URL do proxy.
raw_request_hook	Função de chamada de retorno. Será invocado a pedido.
raw_response_hook	Função de chamada de retorno. Será invocado na resposta.
network_span_namer	Um callable para personalizar o nome do span.
tracing_attributes	Atributos a definir em todos os intervalos criados.
permit_redirects	Se o cliente permite redirecionamentos. Predefinições para True.
redirect_max	Os redirecionamentos máximos permitidos. Predefinições para 30.
retry_total	Número total de tentativas a permitir. Tem precedência sobre outras contagens. O valor predefinido é 10.
retry_connect	Quantos erros relacionados com a ligação deve repetir. Estes são erros gerados antes de o pedido ser enviado para o servidor remoto, que assumimos não ter acionado o servidor para processar o pedido. O valor predefinido é 3.
retry_read	Quantas vezes repetir erros de leitura. Estes erros são gerados após o pedido ter sido enviado para o servidor, pelo que o pedido pode ter efeitos colaterais. O valor predefinido é 3.
retry_status	Quantas vezes repetir em códigos de estado incorretos. O valor predefinido é 3.
retry_backoff_factor	Um fator de recuo a aplicar entre tentativas após a segunda tentativa (a maioria dos erros é resolvida imediatamente por uma segunda tentativa sem demora). A política de repetição irá suspender durante: {backoff factor} * (2 ** ({number of total retries} - 1)) segundos. Se o backoff_factor for 0,1, a repetição irá suspender para [0,0s, 0,2s, 0,4s, ...] entre repetições. O valor predefinido é 0.8.
retry_backoff_max	O tempo máximo de folga. O valor predefinido é 120 segundos (2 minutos).
retry_mode	Atraso fixo ou exponencial entre tentativas, a predefinição é Exponential.
tempo limite	Definição de tempo limite para a operação em segundos, a predefinição é 604800s (7 dias).
connection_timeout	Um único flutuante em segundos para o tempo limite da ligação. A predefinição é 300 segundos.
read_timeout	Um único flutuante em segundos para o tempo limite de leitura. A predefinição é 300 segundos.
connection_verify	Verificação do certificado SSL. Ativado por predefinição. Definido como Falso para desativar, em alternativa, pode ser definido como o caminho para um ficheiro ou diretório CA_BUNDLE com certificados de ACs fidedignas.
connection_cert	Certificados do lado do cliente. Pode especificar um certificado local para utilizar como certificado do lado do cliente, como um único ficheiro (que contém a chave privada e o certificado) ou como uma cadeia de identificação dos caminhos de ambos os ficheiros.
Proxies	Protocolo ou protocolo de mapeamento de dicionários e nome do anfitrião para o URL do proxy.
cookies	Dict or CookieJar object to send with the Request.
connection_data_block_size	O tamanho do bloco dos dados enviados através da ligação. A predefinição é 4096 bytes.

Transporte assíncrono

O transporte assíncrono foi concebido para ser opt-in. O AioHttp é uma das implementações suportadas do transporte assíncrono. Não está instalado por predefinição. Tem de instalá-lo separadamente.

Módulos partilhados

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 suportar enumerações não sensíveis a maiúsculas e minúsculas.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

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

Valor nulo do Sentinel

Um objeto falsy sentinel que é suposto ser utilizado para especificar atributos sem dados. Esta opção é serializada para null na transmissão.

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.