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

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.

Instalacja biblioteki

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).

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.