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

Artikel
10/23/2023

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

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

Konfigurera din lokala utvecklingsmiljö

Om du inte redan har gjort det kan du konfigurera en miljö där du kan köra den här koden. Här följer några alternativ:

Konfigurera en virtuell Python-miljö. Du kan skapa den virtuella miljön lokalt eller i Azure Cloud Shell och köra koden där. Var noga med att aktivera den virtuella miljön för att börja använda den.
Använd en conda-miljö.
Använd en Dev-container i Visual Studio Code eller GitHub Codespaces.

Om du vill installera ett specifikt bibliotekspaket använder du 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 hämtar den senaste versionen av ett bibliotek i din aktuella Python-miljö.

Du kan också använda pip för att avinstallera bibliotek och installera specifika versioner, inklusive förhandsversioner. Mer information finns i Installera Azure-bibliotekspaket för Python.

Om du vill installera ett specifikt bibliotekspaket i en Conda-miljö använder du 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 hämtar den senaste versionen av ett paket i din aktuella Conda-miljö.

Mer information, inklusive hur du tar bort paket eller installerar specifika versioner, finns i Installera Azure-bibliotekspaket för Python.

Asynkrona åtgärder

Asynkrona bibliotek

Många klient- och hanteringsbibliotek tillhandahåller asynkrona versioner (.aio). Biblioteket asyncio har varit tillgängligt sedan Python 3.4 och nyckelorden async/await introducerades i Python 3.5. Asynkrona versioner av biblioteken är avsedda att användas med Python 3.5 och senare.

Exempel på Azure Python SDK-bibliotek med asynkrona versioner är: azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio och azure.mgmt.compute.aio.

Dessa bibliotek behöver en asynkron transport, till exempel aiohttp för att fungera. Biblioteket azure-core tillhandahåller en asynkron transport, AioHttpTransport, som används av asynkrona bibliotek.

Följande kod visar hur du skapar en klient för asynkron version av Azure Blob Storage-biblioteket:

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

Det fullständiga exemplet finns på GitHub på use_blob_auth_async.py. Den synkrona versionen av den här koden finns i Exempel: Ladda upp en blob.

Långvariga åtgärder

Vissa hanteringsåtgärder som du anropar (till exempel ComputeManagementClient.virtual_machines.begin_create_or_update och WebSiteManagementClient.web_apps.begin_create_or_update returnerar en poller för tidskrävande åtgärder, LROPoller[<type>], där <type> är specifik för åtgärden i fråga.

Kommentar

Du kan märka skillnader i metodnamn i ett bibliotek, vilket beror på versionsskillnader. Äldre bibliotek som inte är baserade på azure.core använder vanligtvis namn som create_or_update. Bibliotek baserade på azure.core lägger till prefixet begin_ i metodnamn för att bättre indikera att de är långa avsökningsåtgärder. Att migrera gammal kod till ett nyare azure.core-baserat bibliotek innebär vanligtvis att lägga till prefixet begin_ i metodnamn, eftersom de flesta metodsignaturer förblir desamma.

Returtypen LROPoller innebär att åtgärden är asynkron. Därför måste du anropa den pollerns metod för att vänta tills åtgärden har slutförts result och få resultatet.

Följande kod, hämtad från Exempel: Skapa och distribuera en webbapp, visar ett exempel på hur du använder pollern 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 av begin_create_or_update av typen AzureOperationPoller[Site], vilket innebär att returvärdet poller.result() för är ett webbplatsobjekt.

Undantag

I allmänhet skapar Azure-biblioteken undantag när åtgärder inte kan utföras som avsett, inklusive misslyckade HTTP-begäranden till Azure REST API. För appkod kan du använda try...except block 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 Python-standardbiblioteket logging för att generera loggutdata. Du kan ange loggningsnivån för enskilda bibliotek, biblioteksgrupper 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 Loggning i Azure-biblioteken.

Proxykonfiguration

Om du vill ange en proxy kan du använda miljövariabler eller valfria argument. Mer information finns i Konfigurera proxyservrar.

Valfria argument för klientobjekt och -metoder

I biblioteksreferensdokumentationen ser du ofta ett **kwargs eller **operation_config argument i 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 andra namngivna argument. Referensdokumentationen anger vanligtvis de specifika argument som du kan använda. Det finns också några 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 anges i Python – Nya bibliotek. Här är till exempel en delmängd av nyckelordsargumenten för azure-core. En fullständig lista finns i GitHub README för azure-core.

Namn	Type	Standardvärde	beskrivning
logging_enable	bool	Falsk	Aktiverar loggning. Mer information finns i Loggning i Azure-biblioteken.
proxyservrar	Dict	{}	Url:er för proxyserver. Mer information finns i Konfigurera proxyservrar.
use_env_settings	bool	Sant	Om sant tillåter användning av `HTTP_PROXY` och `HTTPS_PROXY` miljövariabler för proxyservrar. Om det är falskt ignoreras miljövariablerna. Mer information finns i Konfigurera proxyservrar.
connection_timeout	heltal	300	Tidsgränsen i sekunder för att upprätta en anslutning till Azure REST API-slutpunkter.
read_timeout	heltal	300	Tidsgränsen i sekunder för att slutföra en Azure REST API-åtgärd (det vill: väntar på ett svar).
retry_total	heltal	10	Antalet tillåtna återförsök för REST API-anrop. Använd `retry_total=0` för att inaktivera återförsök.
retry_mode	uppräkning	Exponentiell	Tillämpar tidsinställning för återförsök på ett linjärt eller exponentiellt sätt. Om "enkel" görs återförsök med jämna mellanrum. Om det är "exponentiellt" väntar varje nytt försök dubbelt så länge som föregående återförsök.

Enskilda bibliotek är inte skyldiga att stödja något av dessa argument, så se alltid referensdokumentationen för varje bibliotek för exakt information. Dessutom kan varje bibliotek ha stöd för andra argument. För bloblagringsspecifika nyckelordsargument kan du till exempel läsa GitHub README för azure-storage-blob.

Infogat JSON-mönster för objektargument

Med många åtgärder i Azure-biblioteken kan du uttrycka objektargument antingen som diskreta objekt eller som infogad 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 vill anropa create_or_update metoden kan du skapa en diskret instans av ResourceGroup direkt med de argument som krävs (location i det här fallet):

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

Alternativt kan du skicka samma parametrar som infogad JSON:

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

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

Objekt kan också ha kapslade objektargument, i vilket fall du också 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. VaultPropertiesinnehåller i sin tur objektargument av typen Sku och list[AccessPolicyEntry]. A Sku innehåller ett SkuName objekt och var AccessPolicyEntry och en innehåller ett Permissions objekt.

Om du vill anropa begin_create_or_update med inbäddade objekt använder du kod som följande (förutsatt tenant_idatt , object_idoch LOCATION redan har definierats). Du kan också skapa nödvändiga objekt innan 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 = 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()

Samma anrop med infogad 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': 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()

Eftersom båda formulären är likvärdiga kan du välja vad du vill och till och med blanda dem. (Den fullständiga koden för dessa exempel finns på GitHub.)

Om din JSON inte har skapats korrekt får du vanligtvis felet "DeserializationError: Det går inte att deserialisera till objekt: typ, AttributeError: 'str'-objektet har inget attribut 'get'". En vanlig orsak till det här felet är att du anger en enda sträng för en egenskap när biblioteket förväntar sig ett kapslat JSON-objekt. Om du till exempel använder 'sku': 'standard' i föregående exempel genereras det här felet eftersom parametern sku är ett Sku objekt som förväntar sig infogad objekt-JSON, i det här fallet {'name': 'standard'}, som mappar till 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 läsa 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 inte är sekventiella eller beroende.