Knihovny Azure pro vzory použití Pythonu

Článek
10/23/2023

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.

Nastavit místní vývojové prostředí

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

Nakonfigurujte virtuální prostředí Pythonu. Virtuální prostředí můžete vytvořit místně nebo v Azure Cloud Shellu a spustit ho tam. Nezapomeňte aktivovat virtuální prostředí, abyste ho mohli začít používat.
Použijte prostředí Conda.
Použijte vývojový kontejner v editoru Visual Studio Code nebo GitHub Codespaces.

Pokud chcete nainstalovat konkrétní balíček knihovny, použijte 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 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

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ích 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.

Tyto knihovny potřebují asynchronní přenos, například aiohttp k práci. Knihovna azure-core poskytuje asynchronní přenos, AioHttpTransportkterý používá asynchronní knihovny.

Následující kód 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 WebSiteManagementClient.web_apps.begin_create_or_update vrací poller pro dlouhotrvající operace, LROPoller[<type>]kde <type> je specifická pro danou operaci.

Poznámka:

Můžete si všimnout rozdílů v názvech metod v knihovně, což je způsobeno rozdíly mezi verzemi. 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 lépe značily, že se jedná o dlouhé 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 čekat na dokončení operace a získat jeho 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:

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á begin_create_or_update hodnota typu AzureOperationPoller[Site], což znamená, že návratová hodnota poller.result() je site objekt.

Výjimky

Knihovny Azure obecně volají výjimky v případě, že operace neprovedou podle očekávání, včetně neúspěšných požadavků HTTP na rozhraní Azure REST API. 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.

Protokolování

Nejnovější knihovny Azure používají k vygenerování výstupu protokolu standardní logging knihovnu Pythonu. Můžete nastavit úroveň protokolování pro jednotlivé knihovny, skupiny knihoven nebo všechny knihovny. Jakmile zaregistrujete obslužnou rutinu streamu protokolování, můžete povolit protokolování pro konkrétní objekt klienta 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í metody operace zobrazuje **kwargs**operation_config argument nebo argument. 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.

Name	Type	Výchozí	Popis
logging_enable	bool	False	Povolí protokolování. Další informace najdete v tématu Protokolování v knihovnách Azure.
Proxy,	Dict	{}	Adresy URL proxy serveru. Další informace najdete v tématu Konfigurace proxy serverů.
use_env_settings	bool	True	Pokud má hodnotu True, umožňuje použití proměnných `HTTP_PROXYHTTPS_PROXY` prostředí pro proxy servery. Pokud je false, proměnné prostředí se ignorují. Další informace najdete v tématu Konfigurace proxy serverů.
connection_timeout	int	300	Časový limit v sekundách pro vytvoření připojení ke koncovým bodům rozhraní Azure REST API
read_timeout	int	300	Časový limit v sekundách pro dokončení operace rozhraní Azure REST API (to znamená čekání na odpověď).
retry_total	int	10	Počet povolených opakovaných pokusů o volání rozhraní REST API. Slouží `retry_total=0` k zakázání opakování.
retry_mode	enum	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 exponenciální, každý opakovaný pokus počká dvakrát, dokud předchozí opakování nečeká.

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 její create_or_update metodu. 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í pomocí vloženého kódu 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 webu .GitHub.)

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