Udostępniona biblioteka klienta platformy Azure dla języka Python — wersja 1.29.6
Platforma Azure Core udostępnia udostępnione wyjątki i moduły dla bibliotek klienckich zestawu SDK języka Python. Te biblioteki są zgodne z wytycznymi dotyczącymi projektowania zestawu SDK platformy Azure dla języka Python .
Jeśli jesteś deweloperem biblioteki klienta, zapoznaj się z dokumentacją dla deweloperów biblioteki klienta , aby uzyskać więcej informacji.
Kod | źródłowyPakiet (Pypi) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu API
Zrzeczenie odpowiedzialności
Obsługa pakietów języka Python zestawu Azure SDK dla języka Python 2.7 została zakończona 01 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691
Wprowadzenie
Zazwyczaj nie trzeba instalować platformy Azure Core; zostanie ona zainstalowana po zainstalowaniu jednej z bibliotek klienckich przy użyciu niej. Jeśli chcesz ją jawnie zainstalować (aby zaimplementować własną bibliotekę klienta, na przykład), możesz ją znaleźć tutaj.
Kluczowe pojęcia
Wyjątki biblioteki podstawowej platformy Azure
AzureError
AzureError jest podstawowym wyjątkiem dla wszystkich błędów.
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)
komunikat to dowolny komunikat (str), który ma być skojarzony z wyjątkiem.
args są wszelkie dodatkowe args , które mają być dołączone z wyjątkiem.
kwargs to argumenty słów kluczowych do uwzględnienia z wyjątkiem. Użyj błędu słowa kluczowego, aby przekazać wyjątek wewnętrzny i continuation_token odwołania do tokenu, aby kontynuować niekompletną operację.
Następujące wyjątki dziedziczą po usłudze AzureError:
ServiceRequestError
Wystąpił błąd podczas próby wykonania żądania do usługi. Nie wysłano żądania.
ServiceResponseError
Żądanie zostało wysłane, ale klient nie zrozumiał odpowiedzi. Upłynął limit czasu połączenia. Te błędy można ponowić w przypadku operacji idempotentnych lub bezpiecznych.
HttpResponseError
Zostało wykonane żądanie, a kod stanu nie powodzenia został odebrany z usługi.
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)
komunikat to komunikat o błędzie odpowiedzi HTTP (opcjonalnie)
odpowiedź to odpowiedź HTTP (opcjonalnie).
kwargs to argumenty słów kluczowych do uwzględnienia z wyjątkiem.
Następujące wyjątki dziedziczą błąd HttpResponseError:
DecodeError
Wystąpił błąd podczas dese serializacji odpowiedzi.
Niekompletny błądReadError
Wystąpił błąd, jeśli element równorzędny zamyka połączenie, zanim otrzymaliśmy pełną treść komunikatu.
ResourceExistsError
Odpowiedź o błędzie z kodem stanu 4xx. Nie zostanie to podniesione bezpośrednio przez podstawowy potok platformy Azure.
ResourceNotFoundError
Odpowiedź o błędzie, zwykle wyzwalana przez odpowiedź 412 (dla aktualizacji) lub 404 (w przypadku polecenia get/post).
ResourceModifiedError
Odpowiedź na błąd z kodem stanu 4xx, zazwyczaj 412 Konflikt. Nie zostanie to podniesione bezpośrednio przez podstawowy potok platformy Azure.
ResourceNotModifiedError
Odpowiedź o błędzie z kodem stanu 304. Nie zostanie to podniesione bezpośrednio przez podstawowy potok platformy Azure.
ClientAuthenticationError
Odpowiedź o błędzie z kodem stanu 4xx. Nie zostanie to podniesione bezpośrednio przez podstawowy potok platformy Azure.
TooManyRedirectsError
Wystąpił błąd podczas osiągnięcia maksymalnej liczby prób przekierowania. Maksymalną liczbę przekierowań można skonfigurować w polityce przekierowania.
class TooManyRedirectsError(HttpResponseError):
def __init__(self, history, *args, **kwargs):
self.history = history
message = "Reached maximum redirect attempts."
super(TooManyRedirectsError, self).__init__(message, *args, **kwargs)
historia służy do dokumentowania żądań/odpowiedzi, które spowodowały przekierowanie żądań.
args są wszelkie dodatkowe args , które mają być dołączone z wyjątkiem.
kwargs to argumenty słów kluczowych do uwzględnienia z wyjątkiem.
StreamConsumedError
Błąd zgłaszany, jeśli próbujesz uzyskać dostęp do strumienia azure.core.rest.HttpResponse lub azure.core.rest.AsyncHttpResponse po użyciu strumienia odpowiedzi.
StreamClosedError
Błąd zgłaszany, jeśli próbujesz uzyskać dostęp do strumienia azure.core.rest.HttpResponse lub azure.core.rest.AsyncHttpResponse po zamknięciu strumienia odpowiedzi.
ResponseNotReadError
Wystąpił błąd podczas próby uzyskania dostępu do content elementu azure.core.rest.HttpResponse lub azure.core.rest.AsyncHttpResponse przed odczytaniem w bajtach odpowiedzi.
Konfiguracje
Podczas wywoływania metod niektóre właściwości można skonfigurować, przekazując jako argumenty kwargs.
| Parametry | Opis |
|---|---|
| Nagłówki | Nagłówki żądania HTTP. |
| Request_id | Identyfikator żądania, który ma zostać dodany do nagłówka. |
| user_agent | Jeśli zostanie określony, zostanie to dodane przed ciągiem agenta użytkownika. |
| logging_enable | Użyj polecenia , aby włączyć operację. Wartość domyślna to False. |
| Rejestratora | Jeśli zostanie określony, będzie on używany do rejestrowania informacji. |
| response_encoding | Kodowanie do użycia, jeśli jest znane z tej usługi (spowoduje wyłączenie automatycznego wykrywania). |
| serwery proxy | Mapuje protokół lub protokół i nazwę hosta na adres URL serwera proxy. |
| raw_request_hook | Funkcja wywołania zwrotnego. Zostanie wywołana na żądanie. |
| raw_response_hook | Funkcja wywołania zwrotnego. Zostanie wywołana w odpowiedzi. |
| network_span_namer | Obiekt wywołujący w celu dostosowania nazwy zakresu. |
| tracing_attributes | Atrybuty do ustawienia na wszystkich utworzonych zakresach. |
| permit_redirects | Czy klient zezwala na przekierowania. Wartość domyślna to True. |
| redirect_max | Maksymalna dozwolona liczba przekierowań. Wartość domyślna to 30. |
| retry_total | Całkowita liczba ponownych prób, które mają być dozwolone. Ma pierwszeństwo przed innymi liczbami. Wartość domyślna to 10. |
| retry_connect | Ile błędów związanych z połączeniem należy ponowić próbę. Są to błędy zgłaszane przed wysłaniem żądania do serwera zdalnego, który zakładamy, że serwer nie wyzwolił przetwarzania żądania. Wartość domyślna to 3. |
| retry_read | Ile razy ponowić próbę przy błędach odczytu. Te błędy są zgłaszane po wysłaniu żądania do serwera, więc żądanie może mieć skutki uboczne. Wartość domyślna to 3. |
| retry_status | Ile razy należy ponowić próbę w przypadku nieprawidłowych kodów stanu. Wartość domyślna to 3. |
| retry_backoff_factor | Współczynnik wycofywania stosowany między próbami po drugiej próbie (większość błędów jest usuwana natychmiast przez drugą próbę bez opóźnienia). Zasady ponawiania prób będą spać przez: {backoff factor} * (2 ** ({number of total retries} - 1)) sekundy. Jeśli backoff_factor wynosi 0,1, ponawianie próby będzie spać dla [0.0s, 0.2s, 0.4s, ...] między ponownymi próbami. Wartość domyślna to 0.8. |
| retry_backoff_max | Maksymalny czas wolny od pracy. Wartość domyślna to 120 sekundy (2 minuty). |
| retry_mode | Naprawiono lub wykładnicze opóźnienie między próbami, wartość domyślna to Exponential. |
| timeout | Ustawienie limitu czasu dla operacji w sekundach jest wartością domyślną 604800(7 dni). |
| connection_timeout | Pojedynczy zmiennoprzecinkowy w sekundach dla limitu czasu połączenia. Wartości domyślne to 300 sekundy. |
| read_timeout | Pojedynczy zmiennoprzecinkowy w sekundach dla limitu czasu odczytu. Wartości domyślne to 300 sekundy. |
| connection_verify | Weryfikacja certyfikatu SSL. Domyślnie włączony. Ustaw wartość Fałsz, aby wyłączyć, alternatywnie można ustawić ścieżkę do pliku CA_BUNDLE lub katalogu z certyfikatami zaufanych urzędów certyfikacji. |
| connection_cert | Certyfikaty po stronie klienta. Możesz określić lokalny certyfikat, który ma być używany jako certyfikat po stronie klienta, jako pojedynczy plik (zawierający klucz prywatny i certyfikat) lub jako krotka ścieżek obu plików. |
| serwery proxy | Protokół mapowania słownika lub protokół i nazwa hosta na adres URL serwera proxy. |
| Pliki cookie | Obiekt Dict lub CookieJar do wysłania za pomocą polecenia Request. |
| connection_data_block_size | Rozmiar bloku danych wysyłanych przez połączenie. Domyślnie do 4096 bajtów. |
Transport asynchroniczny
Transport asynchroniczny został zaprojektowany tak, aby był opt-in. AioHttp jest jedną z obsługiwanych implementacji transportu asynchronicznego. Nie jest on instalowany domyślnie. Musisz zainstalować go oddzielnie.
Moduły udostępnione
MatchConditions
MatchConditions to wyliczenie opisujące warunki dopasowania.
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
Metaklasa do obsługi wyliczenia bez uwzględniania wielkości liter.
from enum import Enum
from azure.core import CaseInsensitiveEnumMeta
class MyCustomEnum(str, Enum, metaclass=CaseInsensitiveEnumMeta):
FOO = 'foo'
BAR = 'bar'
Wartość sentinel o wartości null
Falsy obiekt sentinel, który ma być używany do określania atrybutów bez danych. Jest to serializowane do null przewodu.
from azure.core.serialization import NULL
assert bool(NULL) is False
foo = Foo(
attr=NULL
)
Współtworzenie
W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.
Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.
W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz artykuł Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania). Jeśli będziesz mieć jeszcze jakieś pytania lub komentarze, wyślij wiadomość e-mail na adres opencode@microsoft.com.
Azure SDK for Python