Compartir a través de

Biblioteca cliente compartida de Azure Core para Python: versión 1.29.6

  • Artículo

Azure Core proporciona excepciones y módulos compartidos para las bibliotecas cliente del SDK de Python. Estas bibliotecas siguen las directrices de diseño del SDK de Azure para Python .

Si es desarrollador de la biblioteca cliente, consulte la referencia para desarrolladores de la biblioteca cliente para obtener más información.

Código | fuentePaquete (Pypi) | Paquete (Conda) | Documentación de referencia de API

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Normalmente, no es necesario instalar azure core; se instalará al instalar una de las bibliotecas cliente con ella. En caso de que quiera instalarlo explícitamente (para implementar su propia biblioteca cliente, por ejemplo), puede encontrarlo aquí.

Conceptos clave

Excepciones de la biblioteca principal de Azure

AzureError

AzureError es la excepción base de todos los errores.

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 es cualquier mensaje (str) que se va a asociar a la excepción.

los argumentos son argumentos adicionales que se van a incluir con excepción.

kwargs son argumentos de palabra clave que se van a incluir con la excepción. Use el error de palabra clave para pasar una excepción interna y continuation_token para una referencia de token para continuar con una operación incompleta.

Las siguientes excepciones heredan de AzureError:

ServiceRequestError

Error al intentar realizar una solicitud al servicio. No se envió ninguna solicitud.

ServiceResponseError

Se envió la solicitud, pero el cliente no pudo comprender la respuesta. Es posible que la conexión haya agotado el tiempo de espera. Estos errores se pueden reintentar para operaciones idempotentes o seguras.

HttpResponseError

Se realizó una solicitud y se recibió un código de estado no correcto del servicio.

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 es el mensaje de error de respuesta HTTP (opcional)

response es la respuesta HTTP (opcional).

kwargs son argumentos de palabra clave que se van a incluir con la excepción.

Las siguientes excepciones heredan de HttpResponseError:

DecodeError

Error generado durante la des serialización de respuesta.

IncompleteReadError

Se produce un error si el mismo nivel cierra la conexión antes de haber recibido el cuerpo completo del mensaje.

ResourceExistsError

Una respuesta de error con el código de estado 4xx. La canalización principal de Azure no generará esto directamente.

ResourceNotFoundError

Una respuesta de error, que normalmente se desencadena mediante una respuesta 412 (para la actualización) o 404 (para get/post).

ResourceModifiedError

Una respuesta de error con el código de estado 4xx, normalmente 412 Conflicto. La canalización principal de Azure no generará esto directamente.

ResourceNotModifiedError

Una respuesta de error con el código de estado 304. La canalización principal de Azure no generará esto directamente.

ClientAuthenticationError

Una respuesta de error con el código de estado 4xx. La canalización principal de Azure no generará esto directamente.

TooManyRedirectsError

Se produce un error cuando se alcanza el número máximo de intentos de redireccionamiento. La cantidad máxima de redireccionamientos se puede configurar en 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)

el historial se usa para documentar las solicitudes o respuestas que dieron lugar a solicitudes redirigidas.

los argumentos son argumentos adicionales que se van a incluir con excepción.

kwargs son argumentos de palabra clave que se van a incluir con la excepción.

StreamConsumedError

Se produce un error si intenta acceder a la secuencia de azure.core.rest.HttpResponse o azure.core.rest.AsyncHttpResponse una vez que se ha consumido la secuencia de respuesta.

StreamClosedError

Se produce un error si intenta acceder a la secuencia de azure.core.rest.HttpResponse o azure.core.rest.AsyncHttpResponse una vez que se ha cerrado la secuencia de respuesta.

ResponseNotReadError

Se produce un error si intenta acceder content primero a o antes de azure.core.rest.AsyncHttpResponseazure.core.rest.HttpResponse leer en los bytes de la respuesta.

Configurations

Al llamar a los métodos, se pueden configurar algunas propiedades pasando como argumentos kwargs.

Parámetros Descripción
headers Encabezados de solicitud HTTP.
request_id Identificador de solicitud que se va a agregar al encabezado.
user_agent Si se especifica, se agregará delante de la cadena del agente de usuario.
logging_enable Use para habilitar por operación. Tiene como valor predeterminado False.
logger Si se especifica, se usará para registrar información.
response_encoding Codificación que se va a usar si se conoce para este servicio (deshabilitará la detección automática).
proxies Asigna el protocolo o el protocolo y el nombre de host a la dirección URL del proxy.
raw_request_hook Función callback. Se invocará a petición.
raw_response_hook Función callback. Se invocará en la respuesta.
network_span_namer Se puede llamar para personalizar el nombre del intervalo.
tracing_attributes Atributos que se van a establecer en todos los intervalos creados.
permit_redirects Si el cliente permite redireccionamientos. Tiene como valor predeterminado True.
redirect_max Redireccionamientos máximos permitidos. Tiene como valor predeterminado 30.
retry_total Número total de reintentos que se van a permitir. Tiene prioridad sobre otros recuentos. El valor predeterminado es 10.
retry_connect Cuántos errores relacionados con la conexión se reintentan. Estos son errores que se producen antes de que la solicitud se envíe al servidor remoto, lo que suponemos que no ha desencadenado el servidor para procesar la solicitud. El valor predeterminado es 3.
retry_read Cuántas veces se reintenta en los errores de lectura. Estos errores se generan después de enviar la solicitud al servidor, por lo que la solicitud puede tener efectos secundarios. El valor predeterminado es 3.
retry_status Cuántas veces se reintenta en códigos de estado incorrectos. El valor predeterminado es 3.
retry_backoff_factor Factor de retroceso que se va a aplicar entre los intentos después del segundo intento (la mayoría de los errores se resuelven inmediatamente mediante un segundo intento sin retraso). La directiva de reintento se suspenderá durante: {backoff factor} * (2 ** ({number of total retries} - 1)) segundos. Si el backoff_factor es 0.1, el reintento se suspenderá para [0.0s, 0.2s, 0.4s, ...] entre reintentos. El valor predeterminado es 0.8.
retry_backoff_max Tiempo de retroceso máximo. El valor predeterminado es 120 segundos (2 minutos).
retry_mode Retraso fijo o exponencial entre intentos, el valor predeterminado es Exponential.
timeout Configuración de tiempo de espera para la operación en segundos, el valor predeterminado es 604800s (7 días).
connection_timeout Un único valor float en segundos para el tiempo de espera de conexión. El valor predeterminado es 300 segundos.
read_timeout Un único valor float en segundos para el tiempo de espera de lectura. El valor predeterminado es 300 segundos.
connection_verify Comprobación del certificado SSL. De forma predeterminada está habilitado. Establézcalo en False para deshabilitarlo; como alternativa, se puede establecer en la ruta de acceso a un archivo o directorio de CA_BUNDLE con certificados de CA de confianza.
connection_cert Certificados del lado cliente. Puede especificar un certificado local que se usará como certificado del lado cliente, como un único archivo (que contiene la clave privada y el certificado) o como una tupla de ambas rutas de acceso de los archivos.
proxies Protocolo de asignación de diccionarios o protocolo y nombre de host a la dirección URL del proxy.
cookies Objeto Dict o CookieJar que se va a enviar con .Request
connection_data_block_size Tamaño del bloque de datos enviados a través de la conexión. El valor predeterminado es 4096 bytes.

Transporte asincrónico

El transporte asincrónico está diseñado para participar. AioHttp es una de las implementaciones admitidas de transporte asincrónico. No está instalado de forma predeterminada. Debe instalarlo por separado.

Módulos compartidos

MatchConditions

MatchConditions es una enumeración para describir las condiciones de coincidencia.

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

Metaclase para admitir enumeraciones que no distinguen mayúsculas de minúsculas.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

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

Valor null de Sentinel

Objeto sentinel falsificado que se supone que se va a usar para especificar atributos sin datos. Esto se serializa en null en el cable.

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.