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

  • Artykuł

Zestaw Azure SDK dla języka Python składa się z wielu niezależnych bibliotek, które są wymienione 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.

Konfigurowanie lokalnego środowiska programistycznego

Jeśli jeszcze tego nie zrobiono, możesz skonfigurować środowisko, w którym można uruchomić ten kod. Oto kilka opcji:

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

Biblioteki asynchroniczne

Wiele bibliotek klienta i zarządzania udostępnia wersje asynchroniczne (.aio). Biblioteka asyncio jest dostępna od wersji 3.4 języka Python, a słowa kluczowe async/await zostały wprowadzone w języku Python 3.5. Wersje asynchroniczne bibliotek mają być używane z językiem Python 3.5 lub nowszym.

Przykłady bibliotek zestawu AZURE Python SDK z wersjami asynchronizowanymi to azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio i azure.mgmt.compute.aio.

Te biblioteki wymagają transportu asynchronicznego, takiego jak aiohttp do pracy. Biblioteka azure-core udostępnia transport asynchroniczny , AioHttpTransportktóry jest używany przez biblioteki asynchroniczne.

Poniższy kod pokazuje, jak utworzyć klienta dla asynchronicznych wersji biblioteki usługi Azure Blob Storage:

credential = DefaultAzureCredential()

async def run():

    async with BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
        credential=credential,
    ) as blob_client:

        # Open a local file and upload its contents to Blob Storage
        with open("./sample-source.txt", "rb") as data:
            await blob_client.upload_blob(data)
            print(f"Uploaded sample-source.txt to {blob_client.url}")

        # Close credential
        await credential.close()

asyncio.run(run())

Pełny przykład znajduje się w witrynie GitHub w use_blob_auth_async.py. Aby uzyskać synchroniczną wersję tego kodu, zobacz Przykład: przekazywanie obiektu blob.

Długotrwałe operacje

Niektóre operacje zarządzania, które są wywoływane (takie jak ComputeManagementClient.virtual_machines.begin_create_or_update i WebSiteManagementClient.web_apps.begin_create_or_update zwracają narzędzie poller dla długotrwałych operacji, LROPoller[<type>], gdzie <type> jest specyficzne dla danej operacji.

Uwaga

Możesz zauważyć różnice w nazwach metod w bibliotece, co jest spowodowane różnicami wersji. Starsze biblioteki, które nie są oparte na pliku azure.core, zwykle używają nazw, takich jak create_or_update. Biblioteki oparte na pliku azure.core dodaj begin_ prefiks do nazw metod, aby lepiej wskazać, że są to długotrwałe operacje sondowania. Migrowanie starego kodu do nowszej biblioteki azure.core zwykle oznacza dodanie prefiksu begin_ do nazw metod, ponieważ większość podpisów metod pozostaje taka sama.

Zwracany LROPoller typ 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: Tworzenie i wdrażanie aplikacji internetowej przedstawia 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ść obiektu jest obiektem lokacji poller.result() .

Wyjątki

Ogólnie rzecz biorąc, biblioteki platformy Azure zgłaszają wyjątki, gdy operacje nie działają zgodnie z oczekiwaniami, w tym żądania HTTP, które zakończyły się niepowodzeniem, do interfejsu API REST platformy Azure. W przypadku kodu aplikacji można 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 biblioteki języka Python logging do generowania danych wyjściowych dziennika. Poziom rejestrowania można ustawić 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 określonej operacji. Aby uzyskać więcej informacji, zobacz Rejestrowanie w bibliotekach platformy Azure.

Konfiguracja serwera proxy

Aby określić serwer proxy, możesz 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 jest wyświetlany **kwargs argument lub **operation_config w podpisie konstruktora obiektu klienta lub określonej metody operacji. Te symbole zastępcze wskazują, że dany obiekt lub metoda może obsługiwać inne 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 azure.core

Te argumenty dotyczą tych bibliotek wymienionych w języku Python — nowe biblioteki. Na przykład poniżej przedstawiono podzbiór argumentów słów kluczowych dla elementu azure-core. Aby uzyskać pełną listę, zobacz plik README usługi GitHub dla platformy azure-core.

Nazwisko 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 bool Prawda Jeśli wartość True, umożliwia 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 ponownych prób wywołań interfejsu API REST. Użyj polecenia retry_total=0 , aby wyłączyć ponawianie prób.
retry_mode wyliczenie Wykładniczej Stosuje chronometraż ponawiania prób w sposób liniowy lub wykładniczy. W przypadku wartości "single" 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, dopóki poprzednia ponowna próba.

Poszczególne biblioteki nie są zobowiązane do obsługi żadnego z tych argumentów, dlatego zawsze zapoznaj się z dokumentacją referencyjną dla każdej biblioteki, aby uzyskać szczegółowe informacje. Ponadto każda biblioteka może obsługiwać inne argumenty. Na przykład w przypadku argumentów słów kluczowych specyficznych dla magazynu obiektów blob zobacz plik README usługi GitHub dla obiektu azure-storage-blob.

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 ResourceManagementClient obiekt, za pomocą którego tworzysz grupę zasobów przy użyciu jej create_or_update metody. Drugim argumentem tej metody jest typ ResourceGroup.

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

# Provision the resource group.
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:

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg", {"location": "centralus"}
)

W przypadku używania wbudowanego kodu 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 sam zawiera argument typu VaultProperties. VaultProperties, z kolei zawiera argumenty obiektów typu Sku i list[AccessPolicyEntry]. Obiekt Sku zawiera SkuName obiekt, a każdy z nich AccessPolicyEntry zawiera Permissions obiekt.

Aby wywołać metodę begin_create_or_update z obiektami osadzonymi, należy użyć kodu podobnego do poniższego (przy założeniu tenant_id, że wartości , object_idi LOCATION są już zdefiniowane). Można również utworzyć niezbędne obiekty przed wywołaniem funkcji.

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = LOCATION,
        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 przy użyciu 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': LOCATION,
        '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ż obie formy są równoważne, możesz wybrać dowolną preferowaną, a nawet przeplatać je. (Pełny kod dla tych przykładów można znaleźć na stronie 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 w 'sku': 'standard' poprzednim przykładzie generuje ten błąd, ponieważ sku parametr jest obiektem Sku , który oczekuje wbudowanego obiektu JSON, 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 sekwencyjne ani współzależne.