Partager via


Bibliothèque de client partagé Azure Core pour Python - version 1.29.6

Azure Core fournit des exceptions et des modules partagés pour les bibliothèques clientes du Kit de développement logiciel (SDK) Python. Ces bibliothèques suivent les instructions de conception du Kit de développement logiciel (SDK) Azure pour Python .

Si vous êtes développeur de bibliothèques clientes, reportez-vous aux informations de référence du développeur de bibliothèque de client pour plus d’informations.

| Code sourcePackage (Pypi) | Package (Conda) | Documentation de référence sur les API

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

En règle générale, vous n’avez pas besoin d’installer Azure Core . il est installé lorsque vous installez l’une des bibliothèques clientes à l’aide de celle-ci. Si vous souhaitez l’installer explicitement (pour implémenter votre propre bibliothèque cliente, par exemple), vous pouvez la trouver ici.

Concepts clés

Exceptions de bibliothèque principale Azure

AzureError

AzureError est l’exception de base pour toutes les erreurs.

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 est tout message (str) à associer à l’exception.

les args sont des args supplémentaires à inclure avec une exception.

Les kwargs sont mot clé arguments à inclure avec l’exception. Utilisez l’erreur mot clé pour passer une exception interne et continuation_token pour une référence de jeton afin de poursuivre une opération incomplète.

Les exceptions suivantes héritent d’AzureError :

ServiceRequestError

Une erreur s’est produite lors de la tentative d’effectuer une demande au service. Aucune demande n’a été envoyée.

ServiceResponseError

La demande a été envoyée, mais le client n’a pas pu comprendre la réponse. La connexion a peut-être expiré. Ces erreurs peuvent être retentées pour des opérations idempotentes ou sécurisées.

HttpResponseError

Une demande a été effectuée et un code de status non réussi a été reçu du service.

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 est le message d’erreur de réponse HTTP (facultatif)

response est la réponse HTTP (facultatif).

Les kwargs sont mot clé arguments à inclure avec l’exception.

Les exceptions suivantes héritent de HttpResponseError :

DecodeError

Erreur générée lors de la désérialisation de la réponse.

IncompleteReadError

Une erreur s’est produite si l’homologue ferme la connexion avant que nous ayons reçu le corps complet du message.

ResourceExistsError

Réponse d’erreur avec status code 4xx. Cela ne sera pas déclenché directement par le pipeline Azure Core.

ResourceNotFoundError

Réponse d’erreur, généralement déclenchée par une réponse 412 (pour la mise à jour) ou 404 (pour get/post).

ResourceModifiedError

Réponse d’erreur avec status code 4xx, généralement 412 Conflict. Cela ne sera pas déclenché directement par le pipeline Azure Core.

ResourceNotModifiedError

Réponse d’erreur avec status code 304. Cela ne sera pas déclenché directement par le pipeline Azure Core.

ClientAuthenticationError

Réponse d’erreur avec status code 4xx. Cela ne sera pas déclenché directement par le pipeline Azure Core.

TooManyRedirectsError

Erreur générée lorsque le nombre maximal de tentatives de redirection est atteint. La quantité maximale de redirections peut être configurée dans 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)

l’historique est utilisé pour documenter les demandes/réponses qui ont donné lieu à des demandes redirigées.

les args sont des args supplémentaires à inclure avec une exception.

Les kwargs sont mot clé arguments à inclure avec l’exception.

StreamConsumedError

Erreur levée si vous essayez d’accéder au flux de azure.core.rest.HttpResponse ou azure.core.rest.AsyncHttpResponse une fois que le flux de réponse a été consommé.

StreamClosedError

Erreur levée si vous essayez d’accéder au flux du azure.core.rest.HttpResponse ou azure.core.rest.AsyncHttpResponse une fois que le flux de réponse a été fermé.

ResponseNotReadError

Erreur levée si vous essayez d’accéder à ou content avant de azure.core.rest.HttpResponseazure.core.rest.AsyncHttpResponse lire d’abord dans les octets de la réponse.

Configurations

Lors de l’appel des méthodes, certaines propriétés peuvent être configurées en passant en tant qu’arguments kwargs.

Paramètres Description
headers En-têtes de requête HTTP.
request_id ID de demande à ajouter à l’en-tête.
user_agent Si elle est spécifiée, elle est ajoutée devant la chaîne de l’agent utilisateur.
logging_enable Utilisez pour activer par opération. La valeur par défaut est False.
logger S’il est spécifié, il sera utilisé pour journaliser les informations.
response_encoding Encodage à utiliser s’il est connu pour ce service (désactive la détection automatique).
des proxies Mappe le protocole ou le protocole et le nom d’hôte à l’URL du proxy.
raw_request_hook Fonction de rappel. Sera appelé sur demande.
raw_response_hook Fonction de rappel. Sera appelé sur la réponse.
network_span_namer Callable pour personnaliser le nom de l’étendue.
tracing_attributes Attributs à définir sur toutes les étendues créées.
permit_redirects Indique si le client autorise les redirections. La valeur par défaut est True.
redirect_max Nombre maximal de redirections autorisées. La valeur par défaut est 30.
retry_total Nombre total de nouvelles tentatives à autoriser. Est prioritaire sur les autres décomptes. La valeur par défaut est 10.
retry_connect Nombre d’erreurs liées à la connexion à retenter. Il s’agit d’erreurs générées avant l’envoi de la demande au serveur distant, qui, selon nous, n’a pas déclenché le serveur pour traiter la demande. La valeur par défaut est 3.
retry_read Nombre de nouvelles tentatives en cas d’erreurs de lecture. Ces erreurs sont générées après l’envoi de la demande au serveur, de sorte que la demande peut avoir des effets secondaires. La valeur par défaut est 3.
retry_status Nombre de tentatives pour des codes de status incorrects. La valeur par défaut est 3.
retry_backoff_factor Facteur d’interruption à appliquer entre les tentatives après la deuxième tentative (la plupart des erreurs sont résolues immédiatement par un deuxième essai sans délai). La stratégie de nouvelle tentative est mise en veille pendant : {backoff factor} * (2 ** ({number of total retries} - 1)) secondes. Si la backoff_factor est 0.1, la nouvelle tentative est mise en veille pour [0.0s, 0.2s, 0.4s, ...] entre les nouvelles tentatives. La valeur par défaut est 0.8.
retry_backoff_max Temps d’arrêt maximal. La valeur par défaut est 120 secondes (2 minutes).
retry_mode Délai fixe ou exponentiel entre les tentatives, la valeur par défaut est Exponential.
timeout Paramètre de délai d’expiration pour l’opération en secondes, la valeur par défaut est 604800s (7 jours).
connection_timeout Un seul float en secondes pour le délai d’expiration de la connexion. La valeur par défaut est 300 secondes.
read_timeout Un seul float en secondes pour le délai de lecture. La valeur par défaut est 300 secondes.
connection_verify Vérification du certificat SSL. Option activée par défaut. Définissez sur False pour désactiver. Vous pouvez également définir le chemin d’accès à un fichier ou répertoire CA_BUNDLE avec des certificats d’autorités de certification approuvées.
connection_cert Certificats côté client. Vous pouvez spécifier un certificat local à utiliser comme certificat côté client, en tant que fichier unique (contenant la clé privée et le certificat) ou en tant que tuple des chemins des deux fichiers.
des proxies Protocole ou protocole de mappage de dictionnaire et nom d’hôte à l’URL du proxy.
cookies Objet Dict ou CookieJar à envoyer avec le Request.
connection_data_block_size Taille de bloc des données envoyées via la connexion. La valeur par défaut est 4096 octets.

Transport asynchrone

Le transport asynchrone est conçu pour être opt-in. AioHttp est l’une des implémentations prises en charge du transport asynchrone. Il n’est pas installé par défaut. Vous devez l’installer séparément.

Modules partagés

MatchConditions

MatchConditions est une énumération pour décrire les conditions de correspondance.

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

Métaclasse pour prendre en charge les énumérations ne respectant pas la casse.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

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

Valeur Sentinel Null

Objet sentinel falsy censé être utilisé pour spécifier des attributs sans données. Cette opération est sérialisée null sur le réseau.

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d'informations, consultez la FAQ du Code de conduite ou contactez opencode@microsoft.com pour toute question ou commentaire supplémentaire.