Användningsmönster för Azure-bibliotek för Python

Azure SDK för Python består endast av många oberoende bibliotek som listas i paketindexet för Python SDK.

Alla bibliotek har vissa gemensamma egenskaper och användningsmönster, till exempel installation och användning av infogade JSON för objektargument.

Biblioteksinstallation

# 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

Asynkrona åtgärder

Många åtgärder som du anropar via klient- och hanteringsklientobjekt (till exempel och ) returnerar ett objekt av typen där är specifikt ComputeManagementClient.virtual_machines.begin_create_or_updateWebSiteManagementClient.web_apps.create_or_update för den aktuella AzureOperationPoller[<type>]<type> åtgärden.

Båda dessa metoder är asynkrona. Skillnaden i metodnamnen beror på versionsskillnader. Äldre bibliotek som inte baseras på azure.core använder vanligtvis namngivna som create_or_update . Bibliotek baserade på azure.core lägger till begin_ prefixet i metodnamnen för att bättre indikera att de är asynkrona. Migrering av gammal kod till ett nyare azure.core-baserat bibliotek innebär vanligtvis att prefixet läggs till i metodnamnen, eftersom de flesta begin_ metodsignaturer förblir desamma.

I båda fallen innebär en AzureOperationPoller returtyp definitivt att åtgärden är asynkron. Därför måste du anropa avsökningsmetoden för result att vänta tills åtgärden har avslutats och få dess resultat.

Följande kod, som kommer från Exempel: Etableraoch distribuera en webbapp , visar ett exempel på hur du använder avsökning för att vänta på ett resultat:

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

I det här fallet är returvärdet begin_create_or_update för av typen , vilket innebär att AzureOperationPoller[Site] returvärdet för är ett poller.result()begin_create_or_update

Undantag

I allmänhet kan Azure-biblioteken skapa undantag när åtgärder inte fungerar som avsett, inklusive misslyckade HTTP-begäranden till Azure-REST API. För appkod kan du sedan använda block try...except runt biblioteksåtgärder.

Mer information om vilken typ av undantag som kan uppstå finns i dokumentationen för åtgärden i fråga.

Loggning

De senaste Azure-biblioteken använder Pythons logging standardbibliotek för att generera loggutdata. Du kan ange loggningsnivå för enskilda bibliotek, grupper av bibliotek eller alla bibliotek. När du har registrerat en loggningsströmhanterare kan du aktivera loggning för ett specifikt klientobjekt eller en specifik åtgärd. Mer information finns i Logga i Azure-biblioteken.

Proxykonfiguration

Om du vill ange en proxyserver kan du använda miljövariabler eller valfria argument. Mer information finns i Så här konfigurerar du proxy.

Valfria argument för klientobjekt och metoder

I biblioteksreferensdokumentationen visas ofta ett - eller -argument i **kwargs**operation_config signaturen för en klientobjektkonstruktor eller en specifik åtgärdsmetod. Dessa platshållare anger att objektet eller metoden i fråga kan ha stöd för ytterligare namngivna argument. Referensdokumentationen anger vanligtvis de specifika argument som du kan använda. Det finns även vissa allmänna argument som ofta stöds enligt beskrivningen i följande avsnitt.

Argument för bibliotek baserade på azure.core

Dessa argument gäller för de bibliotek som listas i Python – Nya bibliotek.

Enskilda bibliotek är inte skyldiga att stödja något av dessa argument, så läs alltid referensdokumentationen för varje bibliotek för mer information.

Argument för icke-kärnbibliotek

Infogade JSON-mönster för objektargument

Med många åtgärder i Azure-biblioteken kan du uttrycka objektargument som diskreta objekt eller som infogade JSON.

Anta till exempel att du har ett ResourceManagementClient -objekt genom vilket du skapar en resursgrupp med dess create_or_update -metod. Det andra argumentet för den här metoden är av typen ResourceGroup .

Om du create_or_update vill anropa kan du skapa en diskret instans av direkt med de argument som krävs ( i ResourceGroup det här location fallet):

rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

Alternativt kan du skicka samma parametrar som infogade JSON:

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

När du använder JSON konverterar Azure-biblioteken automatiskt infogade JSON till lämplig objekttyp för argumentet i fråga.

Objekt kan också ha kapslade objektargument, vilket innebär att du även kan använda kapslad JSON.

Anta till exempel att du har en instans av KeyVaultManagementClient objektet och anropar dess create_or_update -metod. I det här fallet är det tredje argumentet av typen VaultCreateOrUpdateParameters , som i sig innehåller ett argument av typen VaultProperties . VaultProperties, innehåller i sin tur objektargument av typen Sku och list[AccessPolicyEntry] . En Sku innehåller ett SkuName -objekt och var och en innehåller ett AccessPolicyEntryPermissions -objekt.

Om du begin_create_or_update vill anropa med inbäddade objekt använder du kod som följande (förutsatt tenant_id att och redan har object_id definierats). Du kan också skapa nödvändiga objekt före funktionsanropet.

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

Samma anrop med hjälp av infogade JSON visas på följande sätt:

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

Eftersom båda formulären är likvärdiga kan du välja det du föredrar och till och med blanda dem. (Den fullständiga koden för de här exemplen finns på GitHub.)

Om din JSON inte är korrekt utformad får du vanligtvis felet "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'". En vanlig orsak till det här felet är att du anger en sträng för en egenskap när biblioteket förväntar sig ett kapslat JSON-objekt. Om du till exempel använder i föregående exempel genereras det här felet eftersom parametern är ett objekt som förväntar sig "sku": "standard"skuSku infogade objekt-JSON, i det här fallet , som mappar till { "name": "standard"} den förväntade SkuName typen.

Nästa steg

Nu när du förstår de vanliga mönstren för att använda Azure-biblioteken för Python kan du se följande fristående exempel för att utforska specifika scenarier för hantering och klientbibliotek. Du kan prova de här exemplen i valfri ordning eftersom de varken är sekventiella eller beroende av varandra.

• Exempel: Skapa en resursgrupp

• Exempel: Använd Azure Storage

• Exempel: Etablera en webbapp och distribuera kod

• Exempel: Etablera och fråga en databas

• Exempel: Etablera en virtuell dator

• Använda Azure Managed Disks med virtuella datorer

• Slutför en kort undersökning om Azure SDK för Python