Knihovny Azure pro vzory použití Pythonu

Sada Azure SDK pro Python se skládá z mnoha nezávislých knihoven, které jsou uvedené v indexu balíčků Sady Python SDK.

Všechny knihovny sdílejí určité společné charakteristiky a vzory použití, jako je instalace a použití vloženého JSON pro argumenty objektu.

Nastavení místního vývojového prostředí

Pokud jste to ještě neudělali, můžete nastavit prostředí, ve kterém můžete tento kód spustit. Tady jsou některé možnosti:

Nakonfigurujte virtuální prostředí Pythonu pomocí venv nebo libovolného nástroje podle vašeho výběru. Pokud chcete začít používat virtuální prostředí, nezapomeňte ho aktivovat. Pokud chcete nainstalovat Python, přečtěte si téma Instalace Pythonu.

Udeřit
Prostředí PowerShell

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

# PowerShell syntax
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
. .\venv\Scripts\Activate.ps1

Použijte prostředí Conda. Pokud chcete nainstalovat Conda, přečtěte si téma Instalace Miniconda.
Použijte vývojový kontejner v editoru Visual Studio Code nebo GitHub Codespaces.

Instalace knihovny

Zvolte metodu instalace, která odpovídá vašemu nástroji pro správu prostředí Pythonu, buď pip, nebo conda.

jádro
conda

Pokud chcete nainstalovat konkrétní balíček knihovny, použijte 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 načte nejnovější verzi knihovny v aktuálním prostředí Pythonu.

Můžete také použít pip k odinstalaci knihoven a instalaci konkrétních verzí, včetně verzí Preview. Další informace najdete v tématu Postup instalace balíčků knihovny Azure pro Python.

Pokud chcete nainstalovat konkrétní balíček knihovny v prostředí Conda, použijte conda install:

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

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

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

conda install načte nejnovější verzi balíčku v aktuálním prostředí Conda.

Další informace, včetně odebrání balíčků nebo instalace konkrétních verzí, najdete v tématu Postup instalace balíčků knihovny Azure pro Python.

Asynchronní operace

Asynchronní knihovny

Mnoho klientských knihoven a knihoven pro správu poskytuje asynchronní verze (.aio). Knihovna asyncio je k dispozici od Pythonu 3.4 a klíčová slova async/await byla zavedena v Pythonu 3.5. Asynchronní verze knihoven se mají používat s Pythonem 3.5 a novějším.

Mezi příklady knihoven sady Azure Python SDK s asynchronními verzemi patří: azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio a azure.mgmt.compute.aio.

Aby tyto knihovny fungovaly, potřebují asynchronní přenos, například aiohttp. Knihovna azure-core poskytuje asynchronní přenos, AioHttpTransportkterý používá asynchronní knihovny, takže možná nebudete muset instalovat aiohttp samostatně.

Následující kód ukazuje, jak vytvořit soubor Pythonu, který ukazuje, jak vytvořit klienta pro asynchronní verzi knihovny 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())

Úplný příklad je na GitHubu na use_blob_auth_async.py. Synchronní verzi tohoto kódu najdete v části Příklad: Nahrání objektu blob.

Dlouhotrvající operace

Některé operace správy, které vyvoláte (například ComputeManagementClient.virtual_machines.begin_create_or_update a WebAppsClient.web_apps.begin_create_or_update), vrátí poller pro dlouhotrvající operace. LROPoller[<type>], <type> je specifické pro danou operaci.

Poznámka:

Můžete si všimnout rozdílů v názvech metod v knihovně v závislosti na jeho verzi a na tom, jestli je založená na azure.core. Starší knihovny, které nejsou založené na azure.core, obvykle používají názvy jako create_or_update. Knihovny založené na azure.core přidávají předponu begin_ k názvům metod, aby jasněji naznačovaly, že se jedná o dlouhotrvající operace dotazování. Migrace starého kódu do novější knihovny založené na azure.core obvykle znamená přidání begin_ předpony k názvům metod, protože většina podpisů metody zůstává stejná.

Návratový LROPoller typ znamená, že operace je asynchronní. Proto je nutné volat metodu result poller, abyste čekali na dokončení operace a získali její výsledek.

Následující kód z příkladu: Vytvoření a nasazení webové aplikace ukazuje příklad použití poller k čekání na výsledek:



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

V tomto případě je návratová hodnota begin_create_or_update typu AzureOperationPoller[Site], což znamená, že návratová hodnota poller.result() je objekt Site.

Výjimky

Obecně platí, že knihovny Azure vyvolávají výjimky v případě neúspěchu operací, včetně nezdařených požadavků HTTP na rozhraní API Azure REST. Pro kód aplikace můžete použít try...except bloky kolem operací knihovny.

Další informace o typu výjimek, které mohou být vyvolány, naleznete v dokumentaci k dané operaci.

Logování

Nejnovější knihovny Azure používají ke generování protokolového výstupu standardní knihovnu logging Pythonu. Můžete nastavit úroveň protokolování pro jednotlivé knihovny, skupiny knihoven nebo všechny knihovny. Jakmile zaregistrujete obslužnou funkci k záznamovému streamu, můžete poté povolit protokolování pro konkrétní klientský objekt nebo konkrétní operaci. Další informace najdete v tématu Protokolování v knihovnách Azure.

Konfigurace proxy serveru

K určení proxy serveru můžete použít proměnné prostředí nebo volitelné argumenty. Další informace najdete v tématu Konfigurace proxy serverů.

Volitelné argumenty pro klientské objekty a metody

V referenční dokumentaci knihovny se často v podpisu konstruktoru objektu klienta nebo konkrétní operace metody zobrazuje argument **kwargs nebo **operation_config. Tyto zástupné symboly označují, že daný objekt nebo metoda mohou podporovat jiné pojmenované argumenty. Referenční dokumentace obvykle označuje konkrétní argumenty, které můžete použít. Existují také některé obecné argumenty, které jsou často podporovány, jak je popsáno v následujících částech.

Argumenty pro knihovny založené na azure.core

Tyto argumenty platí pro tyto knihovny uvedené v Pythonu – nové knihovny. Tady je například podmnožina argumentů klíčového slova pro azure-core. Úplný seznam najdete v souboru README GitHubu pro azure-core.

Název	Typ	Výchozí	Popis
povolit_protokolování	Booleova hodnota	Nepravda	Povolí protokolování. Další informace najdete v tématu Protokolování v knihovnách Azure.
Proxies	slovník	{}	Adresy URL proxy serveru. Další informace najdete v tématu Konfigurace proxy serverů.
use_env_settings	Booleova hodnota	Pravdivé	Pokud je hodnota True, umožňuje použití proměnných prostředí `HTTP_PROXY` a `HTTPS_PROXY` pro proxy servery. Pokud je false, proměnné prostředí se ignorují. Další informace najdete v tématu Konfigurace proxy serverů.
časový_limit_připojení	int (integer)	300	Časový limit v sekundách pro vytvoření připojení ke koncovým bodům rozhraní Azure REST API
časový_limit_na_čtení	int (integer)	300	Časový limit v sekundách pro dokončení operace rozhraní Azure REST API (to znamená čekání na odpověď).
celkový počet pokusů	int (integer)	10	Počet povolených opakovaných pokusů o volání rozhraní REST API. Slouží `retry_total=0` k zakázání opakování.
režim_opakování	výčet	exponenciální	Použije časování opakování lineárním nebo exponenciálním způsobem. Pokud je "single", opakování se provádí v pravidelných intervalech. Pokud je nastaveno na „exponenciální“, každý opakovaný pokus čeká dvakrát déle než předchozí.

Jednotlivé knihovny nejsou povinny podporovat žádný z těchto argumentů, proto vždy projděte referenční dokumentaci pro každou knihovnu s přesnými podrobnostmi. Každá knihovna může také podporovat další argumenty. Například pro argumenty klíčového slova specifické pro úložiště objektů blob se podívejte na soubor README GitHubu pro azure-storage-blob.

Vložený vzor JSON pro argumenty objektu

Mnoho operací v knihovnách Azure umožňuje vyjádřit argumenty objektů buď jako diskrétní objekty, nebo jako vložený JSON.

Předpokládejme například, že máte ResourceManagementClient objekt, prostřednictvím kterého vytvoříte skupinu prostředků s její create_or_update metodou. Druhý argument této metody je typu ResourceGroup.

Chcete-li volat metodu create_or_update , můžete vytvořit diskrétní instanci ResourceGroup přímo s požadovanými argumenty (location v tomto případě):

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

Alternativně můžete předat stejné parametry jako vložený JSON:

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

Když použijete vložený JSON, knihovny Azure automaticky převedou vložený JSON na odpovídající typ objektu pro daný argument.

Objekty můžou mít také vnořené argumenty objektu, v takovém případě můžete také použít vnořený JSON.

Předpokládejme například, že máte instanci objektu KeyVaultManagementClient a voláte jeho create_or_update. V tomto případě je třetí argument typu VaultCreateOrUpdateParameters, který sám obsahuje argument typu VaultProperties. VaultProperties, dále obsahuje argumenty objektu typu Sku a list[AccessPolicyEntry]. A Sku obsahuje SkuName objekt a každý z nich AccessPolicyEntry obsahuje Permissions objekt.

Chcete-li volat begin_create_or_update s vloženými objekty, použijte kód podobný následujícímu (za předpokladu tenant_id, object_ida LOCATION jsou již definovány). Před voláním funkce můžete také vytvořit potřebné objekty.

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

Stejné volání s použitím inline JSON se zobrazí takto:

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

Vzhledem k tomu, že obě formy jsou ekvivalentní, můžete si vybrat podle toho, co dáváte přednost, a dokonce i intermixovat. (Úplný kód pro tyto příklady najdete na GitHubu.)

Pokud váš JSON není správně vytvořený, obvykle se zobrazí chyba DeserializationError: Nejde deserializovat na objekt: type, AttributeError: 'str' objekt nemá žádný atribut 'get'. Běžnou příčinou této chyby je, že poskytujete jeden řetězec pro vlastnost, když knihovna očekává vnořený objekt JSON. Například použití 'sku': 'standard' v předchozím příkladu vygeneruje tuto chybu, protože sku parametr je Sku objekt, který očekává vložený objekt JSON, v tomto případě {'name': 'standard'}, který se mapuje na očekávaný SkuName typ.

Další kroky

Teď, když rozumíte běžným vzorům pro používání knihoven Azure pro Python, projděte si následující samostatné příklady a prozkoumejte konkrétní scénáře správy a klientské knihovny. Tyto příklady můžete vyzkoušet v libovolném pořadí, protože nejsou sekvenční nebo vzájemně závislé.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-04-24