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

Article
12/14/2023

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 source Package (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 `604800`s (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.