Sdílená klientská knihovna Azure Core pro Python – verze 1.29.6

Článek
12/16/2023

Azure Core poskytuje sdílené výjimky a moduly pro klientské knihovny sady Python SDK. Tyto knihovny se řídí pokyny k návrhu sady Azure SDK pro Python .

Pokud jste vývojář klientské knihovny, další informace najdete v referenčních informacích pro vývojáře klientských knihoven .

Zdrojový kód | Balíček (Pypi) | Balíček (Conda) | Referenční dokumentace k rozhraní API

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Azure Core obvykle nebudete muset instalovat. Nainstaluje se při instalaci některé z klientských knihoven, které ho používáte. Pokud ho chcete nainstalovat explicitně (například kvůli implementaci vlastní klientské knihovny), najdete ho tady.

Klíčové koncepty

Výjimky základní knihovny Azure

Chyba Azure

AzureError je základní výjimkou pro všechny chyby.

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 je libovolná zpráva (str), která má být přidružena k výjimce.

argumenty jsou všechny další argumenty, které mají být zahrnuty s výjimkou.

kwargs jsou argumenty klíčových slov, které se mají zahrnout s výjimkou . Pomocí klíčového slova error předejte vnitřní výjimku a continuation_token , aby odkaz na token pokračoval v neúplné operaci.

Následující výjimky dědí z AzureError:

ServiceRequestError

Při pokusu o vytvoření požadavku na službu došlo k chybě. Nebyla odeslána žádná žádost.

ServiceResponseError

Požadavek byl odeslán, ale klientovi se nepodařilo porozumět odpovědi. Možná vypršel časový limit připojení. Tyto chyby je možné opakovat pro idempotentní nebo bezpečné operace.

HttpResponseError

Byla podána žádost a služba přijala stavový kód, který se nepovedlo.

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)

zpráva je chybová zpráva odpovědi HTTP (volitelné).

odpověď je odpověď HTTP (volitelné).

kwargs jsou argumenty klíčových slov, které se mají zahrnout s výjimkou .

Následující výjimky dědí z chyby HttpResponseError:

Chyba dekódování

Při de serializaci odpovědi došlo k chybě.

IncompleteReadError

Došlo k chybě, když partner ukončí připojení předtím, než obdržíme kompletní text zprávy.

ResourceExistsError

Chybová odpověď se stavovým kódem 4xx. Tato chyba nebude vyvolána přímo základním kanálem Azure.

ResourceNotFoundError

Chybová odpověď, která se obvykle aktivuje odpovědí 412 (pro aktualizaci) nebo 404 (pro get/post).

Chyba ResourceModifiedError

Chybová odpověď se stavovým kódem 4xx, obvykle konflikt 412. Tato chyba nebude vyvolána přímo základním kanálem Azure.

ResourceNotModifiedError

Odpověď na chybu se stavovým kódem 304. Tato chyba nebude vyvolána přímo základním kanálem Azure.

ClientAuthenticationError

Chybová odpověď se stavovým kódem 4xx. Tato chyba nebude vyvolána přímo základním kanálem Azure.

TooManyRedirectsError

Při dosažení maximálního počtu pokusů o přesměrování došlo k chybě. Maximální počet přesměrování je možné nakonfigurovat v 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)

historie slouží k dokumentaci požadavků a odpovědí, které vedly k přesměrovaným žádostem.

argumenty jsou všechny další argumenty, které mají být zahrnuty s výjimkou.

kwargs jsou argumenty klíčových slov, které se mají zahrnout s výjimkou .

StreamConsumedError

Při pokusu o přístup k datovému azure.core.rest.HttpResponse proudu odpovědi nebo azure.core.rest.AsyncHttpResponse po jeho spotřebování dojde k chybě.

StreamClosedError

Při pokusu o přístup k datovému proudu nebo azure.core.rest.AsyncHttpResponse po zavření datového azure.core.rest.HttpResponse proudu odpovědi dojde k chybě.

ResponseNotReadError

Pokud se nejprve pokusíte získat přístup content k souboru azure.core.rest.HttpResponse nebo azure.core.rest.AsyncHttpResponse před čtením v bajtech odpovědi, dojde k chybě.

Konfigurace

Při volání metod lze některé vlastnosti nakonfigurovat předáním jako argumenty kwargs.

Parametry	Description
Záhlaví	Hlavičky požadavku HTTP.
request_id	ID požadavku, které se má přidat do hlavičky.
user_agent	Pokud je zadaný, přidá se před řetězec uživatelského agenta.
logging_enable	Pomocí povolíte jednotlivé operace. Výchozí hodnota je `False`.
Logger	Pokud je zadaný, použije se k protokolování informací.
response_encoding	Kódování, které se má použít, pokud je pro tuto službu známé (zakáže automatické zjišťování).
Proxy,	Mapuje protokol nebo protokol a název hostitele na adresu URL proxy serveru.
raw_request_hook	Funkce zpětného volání Bude vyvolána na žádost.
raw_response_hook	Funkce zpětného volání Bude vyvolána při odpovědi.
network_span_namer	Volání umožňující přizpůsobit název rozsahu.
tracing_attributes	Atributy, které se mají nastavit pro všechny vytvořené rozsahy.
permit_redirects	Určuje, jestli klient povoluje přesměrování. Výchozí hodnota je `True`.
redirect_max	Maximální povolená přesměrování. Výchozí hodnota je `30`.
retry_total	Celkový počet opakovaných pokusů, které se mají povolit. Má přednost před ostatními počty. Výchozí hodnota je `10`.
retry_connect	Kolik chyb souvisejících s připojením se má opakovat. Jedná se o chyby vyvolané před odesláním požadavku na vzdálený server, u kterých předpokládáme, že server neaktivoval zpracování požadavku. Výchozí hodnota je `3`.
retry_read	Kolikrát se má opakovat při čtení chyb. Tyto chyby jsou vyvolány po odeslání požadavku na server, takže požadavek může mít vedlejší účinky. Výchozí hodnota je `3`.
retry_status	Kolikrát se má opakovat chybný stavový kód. Výchozí hodnota je `3`.
retry_backoff_factor	Faktor backoff, který se použije mezi pokusy po druhém pokusu (většina chyb se vyřeší okamžitě druhým pokusem bez zpoždění). Zásady opakování budou v režimu spánku po dobu: `{backoff factor} * (2 ** ({number of total retries} - 1))` sekund. Pokud je backoff_factor 0,1, pak opakování přejde do režimu spánku po dobu [0,0s, 0,2s, 0,4s, ...] mezi opakovanými pokusy. Výchozí hodnota je `0.8`.
retry_backoff_max	Maximální doba návratu. Výchozí hodnota jsou `120` sekundy (2 minuty).
retry_mode	Oprava nebo exponenciální zpoždění mezi pokusy, výchozí hodnota je `Exponential`.
timeout	Nastavení časového limitu operace v sekundách, výchozí hodnota je `604800`s (7 dní).
connection_timeout	Jeden float v sekundách pro vypršení časového limitu připojení. Výchozí hodnota je `300` v sekundách.
read_timeout	Jeden float v sekundách pro vypršení časového limitu čtení. Výchozí hodnota je `300` v sekundách.
connection_verify	Ověření certifikátu SSL. Ve výchozím nastavení povoleno. Pokud chcete nastavit hodnotu False, můžete ji také nastavit na cestu k souboru CA_BUNDLE nebo adresáři s certifikáty důvěryhodných certifikačních autorit.
connection_cert	Certifikáty na straně klienta. Můžete zadat místní certifikát, který se má použít jako certifikát na straně klienta, jako jeden soubor (obsahující privátní klíč a certifikát) nebo jako kolekci členů cest obou souborů.
Proxy,	Slovník mapující protokol nebo protokol a název hostitele na adresu URL proxy serveru.
soubory cookie	Objekt Dict nebo CookieJar k odeslání pomocí `Request`.
connection_data_block_size	Velikost bloku dat odeslaných přes připojení Výchozí hodnota je `4096` bajty.

Asynchronní přenos

Asynchronní přenos je navržený tak, aby byl opt-in. AioHttp je jednou z podporovaných implementací asynchronního přenosu. Ve výchozím nastavení není nainstalovaný. Musíte ho nainstalovat samostatně.

Sdílené moduly

MatchConditions

MatchConditions je výčet, který popisuje podmínky shody.

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

Metaclass pro podporu výčtů bez rozlišování velkých a malých písmen.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

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

Hodnota Null Sentinelu

Falsy sentinel objekt, který se má použít k určení atributů bez dat. To se serializuje na null drátu.

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.

Sdílet prostřednictvím