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.

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 pomocí venv libovolného nástroje nebo nástroje. 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.

Instalace knihovny

# 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

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

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

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.

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.

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

• Příklad: Vytvoření skupiny prostředků

• Příklad: Použití Služby Azure Storage

• Příklad: Vytvoření webové aplikace a nasazení kódu

• Příklad: Vytvoření a dotazování databáze

• Příklad: Vytvoření virtuálního počítače

• Použití Azure Spravované disky s virtuálními počítači

• Dokončení krátkého průzkumu o sadě Azure SDK pro Python