Biblioteki platformy Azure dla wzorców użycia języka Python

Artykuł
04/20/2022
Czas czytania: 6 min

Zestaw Azure SDK dla języka Python składa się wyłącznie z wielu niezależnych bibliotek wymienionych w indeksie pakietów zestawu SDK języka Python.

Wszystkie biblioteki mają pewne typowe cechy i wzorce użycia, takie jak instalacja i użycie wbudowanego kodu JSON dla argumentów obiektów.

Aby zainstalować określony pakiet biblioteki, użyj polecenia pip install:

# Install the management library for Azure Storage
pip install azure-mgmt-storage

# Install the client library for Azure Blob Storage
pip install azure-storage-blob

pip install pobiera najnowszą wersję biblioteki w bieżącym środowisku języka Python.

Można również użyć pip polecenia , aby odinstalować biblioteki i zainstalować określone wersje, w tym wersje zapoznawcza. Aby uzyskać więcej informacji, zobacz How to install Azure library packages for Python (Jak zainstalować pakiety bibliotek platformy Azure dla języka Python).

Aby zainstalować określony pakiet biblioteki w środowisku Conda, użyj polecenia conda install:

# Install the Azyre management library package
conda install azure-mgmt

# Install the client library for Azure Storage
conda install azure-storage

conda install pobiera najnowszą wersję pakietu w bieżącym środowisku Conda.

Aby uzyskać więcej informacji, w tym sposób usuwania pakietów lub instalowania określonych wersji, zobacz How to install Azure library packages for Python (Jak zainstalować pakiety bibliotek platformy Azure dla języka Python).

Operacje asynchroniczne

Wiele operacji wywoływanych za pośrednictwem obiektów klienta i zarządzania (takich jak ComputeManagementClient.virtual_machines.begin_create_or_update i WebSiteManagementClient.web_apps.create_or_update) zwraca obiekt typu AzureOperationPoller[<type>] , w którym <type> jest specyficzny dla danej operacji.

Obie te metody są asynchroniczne. Różnica w nazwach metod jest spowodowana różnicami wersji. Starsze biblioteki, które nie są oparte na usłudze azure.core, zwykle używają nazw, takich jak create_or_update. Biblioteki oparte na usłudze azure.core dodaj begin_ prefiks do nazw metod, aby lepiej wskazać, że są asynchroniczne. Migrowanie starego kodu do nowszej biblioteki opartej na platformie azure.core zwykle oznacza dodanie prefiksu begin_ do nazw metod, ponieważ większość podpisów metod pozostaje taka sama.

W obu przypadkach zwracany AzureOperationPoller typ zdecydowanie oznacza, że operacja jest asynchroniczna. W związku z tym należy wywołać metodę pollera result , aby poczekać na zakończenie operacji i uzyskać jej wynik.

Poniższy kod, pobrany z przykładu: Aprowizuj i wdróż aplikację internetową, pokazuje przykład użycia narzędzia poller do oczekiwania na wynik:

poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,
    WEB_APP_NAME,
    {
        "location": LOCATION,
        "server_farm_id": plan_result.id,
        "site_config": {
            "linux_fx_version": "python|3.8"
        }
    }
)

web_app_result = poller.result()

W tym przypadku zwracana wartość begin_create_or_update jest typu AzureOperationPoller[Site], co oznacza, że zwracana wartość poller.result() jest obiektem lokacji .

Wyjątki

Ogólnie rzecz biorąc, biblioteki platformy Azure zgłaszają wyjątki, gdy operacje nie są wykonywane zgodnie z oczekiwaniami, w tym żądania HTTP nieudane do interfejsu API REST platformy Azure. W przypadku kodu aplikacji można następnie używać try...except bloków wokół operacji biblioteki.

Aby uzyskać więcej informacji na temat typu wyjątków, które mogą zostać zgłoszone, zobacz dokumentację dotyczącą danej operacji.

Rejestrowanie

Najnowsze biblioteki platformy Azure używają standardowej logging biblioteki języka Python do generowania danych wyjściowych dziennika. Można ustawić poziom rejestrowania dla poszczególnych bibliotek, grup bibliotek lub wszystkich bibliotek. Po zarejestrowaniu procedury obsługi strumienia rejestrowania można włączyć rejestrowanie dla określonego obiektu klienta lub konkretnej operacji. Aby uzyskać więcej informacji, zobacz Rejestrowanie w bibliotekach platformy Azure.

Konfiguracja serwera proxy

Aby określić serwer proxy, można użyć zmiennych środowiskowych lub opcjonalnych argumentów. Aby uzyskać więcej informacji, zobacz Jak skonfigurować serwery proxy.

Opcjonalne argumenty dla obiektów i metod klienta

W dokumentacji referencyjnej biblioteki często widać **kwargs argument lub **operation_config w podpisie konstruktora obiektu klienta lub określoną metodę operacji. Te symbole zastępcze wskazują, że dany obiekt lub metoda może obsługiwać dodatkowe nazwane argumenty. Zazwyczaj dokumentacja referencyjna wskazuje konkretne argumenty, których można użyć. Istnieją również pewne ogólne argumenty, które są często obsługiwane zgodnie z opisem w poniższych sekcjach.

Argumenty dla bibliotek opartych na witrynie azure.core

Te argumenty mają zastosowanie do tych bibliotek wymienionych w języku Python — nowe biblioteki.

Nazwa	Typ	Domyślny	Opis
logging_enable	bool	Fałsz	Włącza rejestrowanie. Aby uzyskać więcej informacji, zobacz Rejestrowanie w bibliotekach platformy Azure.
serwery proxy	dict	{}	Adresy URL serwera proxy. Aby uzyskać więcej informacji, zobacz Jak skonfigurować serwery proxy.
use_env_settings	wartość logiczna	Prawda	Jeśli prawda, zezwala na używanie `HTTP_PROXY` zmiennych środowiskowych i `HTTPS_PROXY` dla serwerów proxy. Jeśli wartość False, zmienne środowiskowe są ignorowane. Aby uzyskać więcej informacji, zobacz Jak skonfigurować serwery proxy.
connection_timeout	int	300	Limit czasu w sekundach na nawiązywanie połączenia z punktami końcowymi interfejsu API REST platformy Azure.
read_timeout	int	300	Limit czasu w sekundach na ukończenie operacji interfejsu API REST platformy Azure (czyli oczekiwanie na odpowiedź).
retry_total	int	10	Liczba dozwolonych prób ponawiania prób wywołań interfejsu API REST. Użyj `retry_total=0` polecenia , aby wyłączyć ponawianie prób.
retry_mode	enum	Wykładniczej	Stosuje chronometraż ponawiania prób w sposób liniowy lub wykładniczy. W przypadku "pojedynczego" ponowne próby są wykonywane w regularnych odstępach czasu. Jeśli wartość "wykładnicza", każda ponowna próba będzie czekać dwa razy, o ile poprzednia ponowna próba.

Poszczególne biblioteki nie są zobowiązane do obsługi żadnego z tych argumentów, więc zawsze zapoznaj się z dokumentacją referencyjną dla każdej biblioteki, aby uzyskać szczegółowe informacje.

Argumenty dla bibliotek innych niż core

Nazwa	Typ	Domyślny	Opis
verify	wartość logiczna	Prawda	Sprawdź certyfikat SSL.
cert	Str	Brak	Ścieżka do certyfikatu lokalnego na potrzeby weryfikacji po stronie klienta.
timeout	int	30	Limit czasu nawiązywania połączenia z serwerem w sekundach.
allow_redirects	bool	Fałsz	Włącz przekierowania.
max_redirects	int	30	Maksymalna liczba dozwolonych przekierowań.
serwery proxy	dict	{}	Adres URL serwera proxy. Aby uzyskać więcej informacji, zobacz Jak skonfigurować serwery proxy.
use_env_proxies	bool	Fałsz	Włącz odczytywanie ustawień serwera proxy z lokalnych zmiennych środowiskowych.
Ponownych prób	int	10	Łączna liczba dozwolonych prób ponawiania prób.
enable_http_logger	bool	Fałsz	Włącz dzienniki protokołu HTTP w trybie debugowania.

Wzorzec wbudowanego kodu JSON dla argumentów obiektów

Wiele operacji w bibliotekach platformy Azure umożliwia wyrażenie argumentów obiektów jako obiektów dyskretnych lub jako wbudowany kod JSON.

Załóżmy na przykład, że masz obiekt, za pomocą którego tworzysz grupę ResourceManagementClient zasobów z jej create_or_updatemetodą ). Drugim argumentem tej metody jest typ ResourceGroup.

Aby wywołać metodę create_or_update , możesz utworzyć dyskretne wystąpienie ResourceGroup bezpośrednio z wymaganymi argumentami (location w tym przypadku):

rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

Alternatywnie można przekazać te same parametry co wbudowany kod JSON:

rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg",
    {
        "location": "centralus"
    }
)

W przypadku korzystania z formatu JSON biblioteki platformy Azure automatycznie konwertują wbudowany kod JSON na odpowiedni typ obiektu dla danego argumentu.

Obiekty mogą również mieć zagnieżdżone argumenty obiektów, w tym przypadku można również użyć zagnieżdżonego kodu JSON.

Załóżmy na przykład, że masz wystąpienie KeyVaultManagementClient obiektu i wywołujesz jego create_or_update metodę. W tym przypadku trzeci argument jest typu VaultCreateOrUpdateParameters, który zawiera argument typu VaultProperties. VaultPropertiesz kolei zawiera argumenty obiektów typu Sku i list[AccessPolicyEntry]. Element Sku zawiera SkuName obiekt, a każdy z nich AccessPolicyEntry zawiera Permissions obiekt.

Aby wywołać obiekt begin_create_or_update z osadzonymi obiektami, należy użyć kodu, takiego jak poniższy (przy założeniu tenant_id i object_id są już zdefiniowane). Przed wywołaniem funkcji można również utworzyć niezbędne obiekty.

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = "centralus",
        properties = VaultProperties(
            tenant_id = tenant_id,
            sku = Sku(
                name="standard",
                family="A"
            ),            
            access_policies = [
                AccessPolicyEntry(
                    tenant_id = tenant_id,
                    object_id = object_id,
                    permissions = Permissions(
                        keys = ['all'],
                        secrets = ['all']
                    )
                )
            ]
        )
    )
)

key_vault1 = poller.result()

To samo wywołanie używające wbudowanego kodu JSON jest wyświetlane w następujący sposób:

# Provision a Key Vault using inline JSON
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_B,
    {
        'location': 'centralus',
        'properties': {
            'sku': {
                'name': 'standard',
                'family': 'A'
            },
            'tenant_id': tenant_id,
            'access_policies': [{
                'tenant_id': tenant_id,
                'object_id': object_id,                
                'permissions': {
                    'keys': ['all'],
                    'secrets': ['all']
                }
            }]
        }
    }
)

key_vault2 = poller.result()

Ponieważ oba formularze są równoważne, możesz wybrać dowolną preferowaną, a nawet intermix. (Pełny kod dla tych przykładów można znaleźć w GitHub).

Jeśli kod JSON nie jest poprawnie sformułowany, zazwyczaj występuje błąd "DeserializationError: Nie można deserializować obiektu: type, AttributeError: "str" nie ma atrybutu "get". Częstą przyczyną tego błędu jest podanie pojedynczego ciągu dla właściwości, gdy biblioteka oczekuje zagnieżdżonego obiektu JSON. Na przykład użycie "sku": "standard" w poprzednim przykładzie generuje ten błąd, ponieważ sku parametr jest obiektem Sku , który oczekuje wbudowanego kodu JSON obiektu, w tym przypadku { "name": "standard"}, który mapuje oczekiwany SkuName typ.

Następne kroki

Teraz, gdy znasz typowe wzorce korzystania z bibliotek platformy Azure dla języka Python, zapoznaj się z poniższymi autonomicznymi przykładami, aby zapoznać się z konkretnymi scenariuszami zarządzania i biblioteki klienta. Możesz wypróbować te przykłady w dowolnej kolejności, ponieważ nie są one ani sekwencyjne, ani współzależne.