Knihovny Azure pro vzorce použití Pythonu

Sada Azure SDK for Python se skládá výhradně z mnoha nezávislých knihoven, které jsou uvedeny v indexu balíčku 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 formátu JSON pro argumenty objektu.

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 Azyre management library package
conda install azure-mgmt

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

Asynchronních operace

Mnoho operací, které vyvoláte prostřednictvím klientských objektů klienta a správy (například ComputeManagementClient.virtual_machines.begin_create_or_update a WebSiteManagementClient.web_apps.create_or_update ), vrátí objekt typu, AzureOperationPoller[<type>] kde <type> je specifický pro danou operaci.

Obě tyto metody jsou asynchronní. Rozdíl v názvech metod je způsoben rozdíly v verzích. Starší knihovny, které nejsou založené na Azure. Core obvykle používají pojmenované jako create_or_update . Knihovny založené na Azure. Core přidávají begin_ předponu do názvů metod, aby lépe označovali, že jsou asynchronní. Migrace starého kódu do novější knihovny založené na Azure. Core obvykle znamená přidání begin_ předpony do názvů metod, protože většina signatur metod zůstává stejná.

V obou případech AzureOperationPoller návratový typ jednoznačně znamená, že operace je asynchronní. Proto je nutné zavolat metodu tohoto dotazovacího nástroje, result aby čekala na dokončení operace a získala výsledek.

Následující kód, který je pořízený z příkladu: zřízení a nasazení webové aplikace, ukazuje příklad použití nástroje pro hlasování 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ě návratová hodnota begin_create_or_update je typu AzureOperationPoller[Site] , což znamená, že návratová hodnota poller.result() je objekt begin_create_or_update .

Výjimky

Obecně platí, že knihovny Azure vyvolají výjimky v případě, že se operace nezdaří, a to včetně neúspěšných požadavků HTTP na REST API Azure. 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, najdete v dokumentaci k příslušné operaci.

protokolování

Nejnovější knihovny Azure používají logging ke generování výstupu protokolu standardní knihovnu Pythonu. Úroveň protokolování můžete nastavit pro jednotlivé knihovny, skupiny knihoven nebo všechny knihovny. Po registraci obslužné rutiny streamu protokolování můžete povolit protokolování pro určitý objekt klienta nebo konkrétní operaci. Další informace najdete v tématu protokolování do knihoven Azure.

Konfigurace proxy serveru

Chcete-li zadat proxy server, můžete použít proměnné prostředí nebo nepovinné argumenty. Další informace najdete v tématu Postup konfigurace proxy serverů.

Volitelné argumenty pro klientské objekty a metody

V referenční dokumentaci knihovny často vidíte **kwargs**operation_config argument nebo v signatuře konstruktoru objektu klienta nebo konkrétní metody operace. Tyto zástupné symboly označují, že objekt nebo metoda, které jsou v dotazu, mohou podporovat další pojmenované argumenty. Referenční dokumentace obvykle indikuje 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 se vztahují na knihovny uvedené v Pythonu – nové knihovny.

Jednotlivé knihovny nejsou povinny podporovat žádný z těchto argumentů, takže si vždy přečtěte referenční dokumentaci ke každé knihovně, kde najdete přesné podrobnosti.

Argumenty pro jiné než základní knihovny

Vložený vzor JSON pro argumenty objektu

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

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

Pro volání create_or_update můžete vytvořit diskrétní instanci ResourceGroup přímo s jejími povinnými argumenty ( location v tomto případě):

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:

rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg",
    {
        "location": "centralus"
    }
)

Při použití formátu JSON knihovny Azure automaticky převádějí vložený formát JSON na příslušný typ objektu pro daný argument.

Objekty mohou také obsahovat vnořené argumenty objektu. v takovém případě můžete také použít vnořený kód JSON.

Předpokládejme například, že máte instanci KeyVaultManagementClient objektu a zavoláte jeho create_or_update metodu. V tomto případě je třetí argument typu VaultCreateOrUpdateParameters , který obsahuje argument typu VaultProperties . VaultProperties, zase obsahuje argumenty objektu typu Sku a list[AccessPolicyEntry] . SkuObsahuje SkuName objekt, který AccessPolicyEntry obsahuje objekt Permissions .

Chcete-li volat begin_create_or_update pomocí vložených objektů, použijte kód podobný následujícímu (za předpokladu, že tenant_id a object_id jsou již definovány). Je také možné vytvořit potřebné objekty před voláním funkce.

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = "centralus",
        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 formátu 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': 'centralus',
        '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 zvolit, co dáváte přednost, a dokonce je Intermix. (Úplný kód pro tyto příklady najdete na GitHub.)

Pokud váš kód JSON není správně vytvořený, obdržíte obvykle chybu "DeserializationError: nejde deserializovat do objektu: Type, AttributeError: objekt str 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 generuje tuto chybu, protože sku parametr je Sku objekt, který očekává vložený vložený objekt JSON, v tomto případě { "name": "standard"} , který je namapován 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, si přečtěte 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 ani sekvenční ani vzájemně závislé.

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

• Příklad: použití Azure Storage

• Příklad: zřízení webové aplikace a nasazení kódu

• Příklad: zřízení a dotazování databáze

• Příklad: zřízení virtuálního počítače

• Použití Managed Disks Azure s virtuálními počítači

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