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

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, hozzon létre egy környezetet, ahol futtathatja ezt a kódot. Íme néhány lehetőség:

  • Python virtuális környezetet konfiguráljon a venv használatával vagy az Ön által választott eszközzel. A virtuális környezet használatának megkezdéséhez feltétlenül aktiválja azt. A Python telepítéséhez lásd a Python telepítését.

    #!/bin/bash
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
source .venv/Scripts/activate # only required for Windows (Git Bash)

  • Használjon conda környezetet. A Conda telepítéséhez lásd a Miniconda telepítése című témakört.

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

Kódtár telepítése

Válassza ki a Python környezetkezelési eszközének megfelelő telepítési módszert, akár pip, akár conda.

Egy adott kódtárcsomag telepítéséhez használja a következőt pip install:

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

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 használható pip . További információ: Azure Library-csomagok telepítése Pythonhoz.

Aszinkron műveletek

Aszinkron könyvtá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, ezért előfordulhat, hogy nem kell külön telepítenie aiohttp .

Az alábbi kód bemutatja, hogyan hozhat létre Python fájlt, amely bemutatja, hogyan hozhat létre ügyfelet a Azure Blob Storage tá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_update és WebAppsClient.web_apps.begin_create_or_update), egy lekérdezőt ad vissza a hosszú ideig futó műveletek kezelésére, LROPoller[<type>], ahol <type> az adott művelet sajátossága.

Megjegyzés:

Előfordulhat, hogy eltéréseket észlel egy kódtár metódusneveiben attól függően, hogy melyik verzióról van szó, illetve hogy az azure.core-ra épül-e. 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 az előtagot a begin_ metódusnevekhez adják hozzá, hogy jobban jelezzék, hogy ezek 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 result metódusát, hogy megvárja, amíg a művelet befejeződik, és annak eredményét megkapja.

A következő kód, amely a Példa: Webalkalmazás létrehozása és üzembe helyezése című példából származik, bemutatja, hogyan lehet a poller segítségével megvárni az eredményt:



# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.

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 begin_create_or_update visszatérési értéke a AzureOperationPoller[Site] típusú, ami azt jelenti, hogy a poller.result() visszatérési érték egy Site 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 használjon try...except blokkokat a kódtár műveleteihez.

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.

Fakitermelé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áljon környezeti változókat vagy opcionális argumentumokat. További információ: Proxyk konfigurálása.

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

A könyvtár referenciadokumentációjában gyakran találkozhatunk **kwargs vagy **operation_config argumentummal egy ügyfélobjektum-konstruktor vagy egy adott művelet metódusának szignatúrájá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 felsorolja a használható argumentumokat. A következő szakaszok néhány általános argumentumot ismertetnek, amelyek gyakran támogatottak.

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

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

Név Típus Alapértelmezett Leírás
naplózás_engedélyezés Bool Téves Engedélyezi a naplózást. További információ: Naplózás az Azure-kódtárakban.
proxyk szótár {} Proxykiszolgáló URL-címei. További információ: Proxyk konfigurálása.
környezet_beállítások_használata Bool Igaz Ha igaz, az ügyfél a proxykhoz használ HTTP_PROXY és HTTPS_PROXY környezeti változókat. Ha hamis, az ügyfél figyelmen kívül hagyja a környezeti változókat. További információ: Proxyk konfigurálása.
kapcsolódási időkorlát Int 300 Az Azure REST API-végpontokkal való kapcsolat létrehozásához szükséges időtúllépés másodpercben.
olvasási_időtúllépés Int 300 Az Azure REST API-művelet végrehajtásának időtúllépése másodpercben (azaz válaszra vár).
újrapróbálási_összeg Int 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 .
újrapróbálási_mód felsorolás exponenciális Lineáris vagy exponenciális módon alkalmazza az újrapróbálkozási időzítést. Ha single, az újrapróbálkozások rendszeres időközönként történnek. Ha exponential, 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

A Azure-kódtárak számos művelete különálló objektumként vagy beágyazott JSON-ként fogadja el az objektumargumentumokat.

Tegyük fel például, hogy rendelkezik egy ResourceManagementClient objektummal, amellyel a(z) create_or_update metódus használatával hoz létre egy erőforráscsoportot. A metódus második argumentuma ResourceGroup típusú.

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 egy KeyVaultManagementClient objektum példányával, és meghívja annak create_or_update-ját. Ebben az esetben a harmadik argumentum típus VaultCreateOrUpdateParameters, amely maga is tartalmaz egy típus VaultPropertiesargumentumot . VaultProperties viszont Sku és list[AccessPolicyEntry] típusú 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 használja a következőhöz hasonló kódot (feltéve, hogy tenant_id, object_idés 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 megtalálható a GitHubon.)

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 ez a hiba azért fordul elő, mert a 'sku': 'standard'sku paraméter egy Sku 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.

  • Last updated on