Azure-kódtárak Python-használati mintákhoz

  • Cikk

Az Azure SDK for Python számos független kódtárból áll, amelyek szerepelnek a Python SDK-csomagindexében.

Minden kódtár közös jellemzőkkel és használati mintákkal rendelkezik, például a telepítéssel és a beágyazott JSON használatával az objektumargumentumokhoz.

A helyi fejlesztési környezet beállítása

Ha még nem tette meg, beállíthat egy környezetet, ahol futtathatja ezt a kódot. Íme néhány lehetőség:

  • Python virtuális környezet konfigurálása. Létrehozhatja a virtuális környezetet helyileg vagy az Azure Cloud Shellben, és ott futtathatja a kódot. Mindenképpen aktiválja a virtuális környezetet a használat megkezdéséhez.

  • Használjon conda környezetet.

  • Használjon Dev-tárolót a Visual Studio Code-ban vagy a GitHub Codespace-ben.

Kódtár telepítése

Egy adott kódtárcsomag telepítéséhez használja a következőt 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 Lekéri egy kódtár legújabb verzióját az aktuális Python-környezetben.

A kódtárak eltávolítására és bizonyos verziók, köztük az előzetes verziók telepítésére is használható pip . További információ: Azure Library-csomagok telepítése Pythonhoz.

Aszinkron műveletek

Aszinkron kódtárak

Számos ügyfél- és felügyeleti kódtár biztosít aszinkron verziót (.aio). A asyncio kódtár a Python 3.4 óta érhető el, és a Python 3.5-ben bevezették az aszinkron/várakozási kulcsszavakat. A kódtárak aszinkron verziói a Python 3.5-ös és újabb verzióival használhatók.

Az aszinkron verziójú Azure Python SDK-kódtárak például a következők: azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio és azure.mgmt.compute.aio.

Ezeknek a kódtáraknak aszinkron átvitelre, például aiohttp működésre van szükségük. A azure-core kódtár aszinkron átvitelt biztosít, AioHttpTransportamelyet az aszinkron kódtárak használnak.

Az alábbi kód bemutatja, hogyan hozhat létre ügyfelet az Azure Blob Storage-kódtár aszinkron verziójához:

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

A teljes példa a GitHubon található use_blob_auth_async.py. A kód szinkron verziójáról lásd : Példa: Blob feltöltése.

Hosszú ideig futó műveletek

Néhány olyan felügyeleti művelet, amelyet meghív (például ComputeManagementClient.virtual_machines.begin_create_or_updateWebSiteManagementClient.web_apps.begin_create_or_update egy lekérdezést a hosszú ideig futó műveletekhez, LROPoller[<type>]ahol <type> a szóban forgó műveletre jellemző).

Feljegyzés

A kódtárakban a metódusnevekben eltéréseket tapasztalhat, ami a verzióeltérésnek köszönhető. A régebbi, nem azure.core-alapú kódtárak általában olyan neveket használnak, mint a create_or_update. Az azure.core-alapú kódtárak hozzáadják az előtagot a begin_ metódusnevekhez, hogy jobban jelezzék, hogy hosszú lekérdezési műveletek. A régi kód egy újabb azure.core-alapú kódtárba való migrálása általában azt jelenti, hogy hozzáadja az előtagot a begin_ metódusnevekhez, mivel a legtöbb metódus-aláírás változatlan marad.

A LROPoller visszatérési típus azt jelenti, hogy a művelet aszinkron. Ennek megfelelően meg kell hívnia a poller metódusát result , hogy várja meg, amíg a művelet befejeződik, és megkapja annak eredményét.

A következő, webalkalmazás létrehozása és üzembe helyezése című példából vett kód egy példát mutat be arra, hogy a lekérdezés használatával várja meg az eredményt:

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

Ebben az esetben a visszatérési begin_create_or_update érték típus AzureOperationPoller[Site], ami azt jelenti, hogy a visszatérési poller.result() érték egy Hely objektum.

Kivételek

Az Azure-kódtárak általában kivételeket emelnek ki, ha a műveletek nem a kívánt módon hajthatók végre, beleértve az Azure REST API-nak küldött sikertelen HTTP-kéréseket is. Alkalmazáskód esetén blokkokat használhat try...except a kódtárműveletek körül.

Az esetlegesen felmerülő kivételek típusával kapcsolatos további információkért tekintse meg a szóban forgó művelet dokumentációját.

Naplózás

A legutóbbi Azure-kódtárak a Python standard logging kódtárat használják a naplókimenet létrehozásához. Beállíthatja az egyes kódtárak, kódtárcsoportok vagy az összes tár naplózási szintjét. Miután regisztrál egy naplózási adatfolyam-kezelőt, engedélyezheti a naplózást egy adott ügyfélobjektumhoz vagy egy adott művelethez. További információ: Naplózás az Azure-kódtárakban.

Proxy konfigurálása

Proxy megadásához használhat környezeti változókat vagy választható argumentumokat. További információ: Proxyk konfigurálása.

Nem kötelező argumentumok ügyfélobjektumokhoz és metódusokhoz

A kódtár referenciadokumentációjában gyakran megjelenik egy **kwargs**operation_config vagy több argumentum egy ügyfélobjektum-konstruktor vagy egy adott műveleti módszer aláírásában. Ezek a helyőrzők azt jelzik, hogy a szóban forgó objektum vagy metódus más nevesített argumentumokat is támogathat. A referenciadokumentáció általában a használható argumentumokat jelzi. Vannak olyan általános argumentumok is, amelyek gyakran támogatottak az alábbi szakaszokban leírtak szerint.

Az azure.core-on alapuló kódtárak argumentumai

Ezek az argumentumok a Python – Új kódtárakban felsorolt kódtárakra vonatkoznak. Íme például a kulcsszóargumentumok azure-coreegy részhalmaza. A teljes listát az Azure-core GitHub README-ében találja.

Név Típus Alapértelmezett Leírás
logging_enable logikai Hamis Engedélyezi a naplózást. További információ: Naplózás az Azure-kódtárakban.
proxyk diktálás {} Proxykiszolgáló URL-címei. További információ: Proxyk konfigurálása.
use_env_settings logikai Igaz Ha igaz, lehetővé teszi a HTTP_PROXY proxyk használatát és HTTPS_PROXY a környezeti változókat. Ha hamis, a környezeti változók figyelmen kívül lesznek hagyva. További információ: Proxyk konfigurálása.
connection_timeout egész 300 Az Azure REST API-végpontokkal való kapcsolat létrehozásához szükséges időtúllépés másodpercben.
read_timeout egész 300 Az Azure REST API-művelet végrehajtásának időtúllépése másodpercben (azaz válaszra vár).
retry_total egész 10 A REST API-hívások engedélyezett újrapróbálkozási kísérleteinek száma. Az újrapróbálkozések letiltására használható retry_total=0 .
retry_mode Enum Exponenciális Lineáris vagy exponenciális módon alkalmazza az újrapróbálkozási időzítést. Ha "önálló", az újrapróbálkozások rendszeres időközönként történnek. Ha "exponenciális", minden újrapróbálkozás kétszer annyi ideig vár, mint az előző újrapróbálkozás.

Az egyes kódtárak nem kötelesek ezen argumentumok egyikét sem támogatni, ezért a pontos részletekért mindig tekintse meg az egyes kódtárak referenciadokumentációját. Emellett az egyes kódtárak más argumentumokat is támogathatnak. Blob Storage-specifikus kulcsszóargumentumok esetén például tekintse meg az Azure-Storage-blob GitHub README-ját.

Beágyazott JSON-minta objektumargumentumokhoz

Az Azure-kódtárakon belüli számos művelet lehetővé teszi az objektumargumentumok diszkrét objektumokként vagy beágyazott JSON-ként történő kifejezését.

Tegyük fel például, hogy van egy ResourceManagementClient objektuma, amelyen keresztül létrehoz egy erőforráscsoportot annak metódusával create_or_update . A metódus második argumentuma típus.ResourceGroup

A create_or_update metódus meghívásához létrehozhat egy különálló példányt ResourceGroup közvetlenül a szükséges argumentumokkal (location ebben az esetben):

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

Másik lehetőségként ugyanazokat a paramétereket adhatja át, mint a beágyazott JSON:

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

Beágyazott JSON használatakor az Azure-kódtárak automatikusan átalakítják a beágyazott JSON-t a szóban forgó argumentum megfelelő objektumtípusára.

Az objektumok beágyazott objektumargumentumokkal is rendelkezhetnek, ebben az esetben beágyazott JSON-t is használhat.

Tegyük fel például, hogy rendelkezik az KeyVaultManagementClient objektum egy példányával, és meghívja annak metódusát create_or_update . Ebben az esetben a harmadik argumentum típus VaultCreateOrUpdateParameters, amely maga is tartalmaz egy típus VaultPropertiesargumentumot . VaultProperties, viszont a típus és list[AccessPolicyEntry]a . típusú Sku objektumargumentumokat tartalmaz. Az A Sku tartalmaz egy objektumot SkuName , és mindegyik AccessPolicyEntry tartalmaz egy objektumot Permissions .

Beágyazott objektumokkal való híváshoz begin_create_or_update az alábbihoz hasonló kódot kell használnia (feltételezve tenant_id, object_idhogy LOCATION már definiálva van). A függvényhívás előtt is létrehozhatja a szükséges objektumokat.

# 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()

Ugyanez a hívás a beágyazott JSON használatával az alábbiak szerint jelenik meg:

# 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()

Mivel mindkét űrlap egyenértékű, kiválaszthatja, hogy melyiket szeretné, és akár össze is keverheti őket. (A példák teljes kódja a következő oldalon található: GitHub.)

Ha a JSON nem megfelelően van kialakítva, általában a következő hibaüzenet jelenik meg: "DeserializationError: Nem lehet deszerializálni az objektumot: type, AttributeError: 'str' objektum nem rendelkezik "get" attribútummal. A hiba gyakori oka, hogy egyetlen sztringet ad meg egy tulajdonsághoz, amikor a kódtár beágyazott JSON-objektumot vár. Az előző példában például ez a hiba azért fordul elő, 'sku': 'standard' mert a sku paraméter egy Sku olyan objektum, amely beágyazott JSON objektumot vár, ebben az esetben {'name': 'standard'}, amely a várt SkuName típusra van leképezve.

Következő lépések

Most, hogy megismerte az Azure-kódtárak Pythonhoz való használatának gyakori mintáit, tekintse meg az alábbi különálló példákat a konkrét felügyeleti és ügyfélkódtár-forgatókönyvek megismeréséhez. Ezeket a példákat bármilyen sorrendben kipróbálhatja, mivel azok nem egymástól vagy egymástól függenek.