Azure-Bibliotheken für Python-Verwendungsmuster

2025-06-21

Das Azure SDK für Python besteht aus vielen unabhängigen Bibliotheken, die im Python SDK-Paketindex aufgeführt sind.

Alle Bibliotheken teilen bestimmte allgemeine Merkmale und Verwendungsmuster, z. B. Installation und Verwendung von Inline-JSON für Objektargumente.

Einrichten Ihrer lokalen Entwicklungsumgebung

Falls noch nicht geschehen, können Sie eine Umgebung einrichten, in der Sie diesen Code ausführen können. Hier sind einige Optionen:

Konfigurieren Sie eine virtuelle Python-Umgebung mit venv oder Ihrem Wahltool. Um mit der Verwendung der virtuellen Umgebung zu beginnen, müssen Sie sie aktivieren. Informationen zum Installieren von Python finden Sie unter Installieren von Python.

Schlagen
PowerShell

#!/bin/bash
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
source .venv/Scripts/activate # only required for Windows (Git Bash)

# PowerShell syntax
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
. .\venv\Scripts\Activate.ps1

Verwenden Sie eine conda-Umgebung. Informationen zum Installieren von Conda finden Sie unter Installieren von Miniconda.
Verwenden Sie einen Dev Container in Visual Studio Code oder GitHub Codespaces.

Bibliotheksinstallation

Wählen Sie die Installationsmethode aus, die Ihrem Python-Umgebungsverwaltungstool entspricht, entweder Pip oder Conda.

Kern
conda

Verwenden Sie pip installfolgendes, um ein bestimmtes Bibliothekspaket zu installieren:

REM Install the management library for Azure Storage
pip install azure-mgmt-storage

REM Install the client library for Azure Blob Storage
pip install azure-storage-blob

REM Install the azure identity library for Azure authentication
pip install azure-identity

pip install Ruft die neueste Version einer Bibliothek in Ihrer aktuellen Python-Umgebung ab.

Sie können mit pip auch Bibliotheken deinstallieren und bestimmte Versionen installieren, einschließlich Vorschauversionen. Weitere Informationen finden Sie unter Installieren von Azure-Bibliothekspaketen für Python.

Verwenden Sie conda installfolgendes, um ein bestimmtes Bibliothekspaket in einer Conda-Umgebung zu installieren:

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

conda install Ruft die neueste Version eines Pakets in Ihrer aktuellen Conda-Umgebung ab.

Weitere Informationen, einschließlich des Entfernens von Paketen oder Installieren bestimmter Versionen, finden Sie unter Installieren von Azure-Bibliothekspaketen für Python.

Asynchrone Vorgänge

Asynchrone Bibliotheken

Viele Client- und Verwaltungsbibliotheken bieten asynchrone Versionen (.aio). Die asyncio Bibliothek ist seit Python 3.4 verfügbar, und die asynchronen/await-Schlüsselwörter wurden in Python 3.5 eingeführt. Die asynchronen Versionen der Bibliotheken sollen mit Python 3.5 und höher verwendet werden.

Beispiele für Azure Python SDK-Bibliotheken mit asynchronen Versionen sind : azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio und azure.mgmt.compute.aio.

Diese Bibliotheken benötigen einen asynchronen Transport wie aiohttp, um zu funktionieren. Die azure-core Bibliothek stellt einen asynchronen Transport bereit, AioHttpTransportder von den asynchronen Bibliotheken verwendet wird, sodass Sie möglicherweise nicht separat installieren aiohttp müssen.

Der folgende Code zeigt, wie Sie eine Python-Datei erstellen, die veranschaulicht, wie Sie einen Client für die asynchrone Version der Azure Blob Storage-Bibliothek erstellen:

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

Das vollständige Beispiel befindet sich auf GitHub auf use_blob_auth_async.py. Die synchrone Version dieses Codes finden Sie unter Beispiel: Hochladen eines Blobs.

Lang andauernde Vorgänge

Einige Verwaltungsvorgänge, die Sie aufrufen (z. B. ComputeManagementClient.virtual_machines.begin_create_or_update und WebAppsClient.web_apps.begin_create_or_update) geben einen Poller für Vorgänge mit langer Ausführung zurück, LROPoller[<type>], wobei <type> für den betreffenden Vorgang spezifisch ist.

Hinweis

Je nach Version können Sie Unterschiede bei den Methodennamen in einer Bibliothek feststellen und ob sie auf "azure.core" basiert. Ältere Bibliotheken, die nicht auf azure.core basieren, verwenden in der Regel Namen wie create_or_update. Bibliotheken, die auf azure.core basieren, fügen das Präfix begin_ zu Methodennamen hinzu, um besser anzugeben, dass es sich um Langpolling-Operationen handelt. Das Migrieren von altem Code zu einer neueren azure.core-basierten Bibliothek bedeutet in der Regel das Hinzufügen des begin_ Präfixes zu Methodennamen, da die meisten Methodensignaturen unverändert bleiben.

Der LROPoller Rückgabetyp bedeutet, dass der Vorgang asynchron ist. Dementsprechend muss die Methode result dieses Pollers so aufgerufen werden, dass auf den Abschluss des Vorgangs gewartet und dann das entsprechende Ergebnis abgerufen wird.

Der folgende Code aus Beispiel: Erstellen und Bereitstellen einer Web-App zeigt ein Beispiel für die Verwendung des Pollers, um auf ein Ergebnis zu warten:



# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.

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

In diesem Fall ist der Rückgabewert begin_create_or_update vom Typ AzureOperationPoller[Site], was bedeutet, dass der Rückgabewert poller.result() ein Site-Objekt ist.

Ausnahmen

Im Allgemeinen lösen die Azure-Bibliotheken Ausnahmen aus, wenn Vorgänge nicht wie beabsichtigt ausgeführt werden können, einschließlich fehlgeschlagener HTTP-Anforderungen an die Azure REST-API. Für App-Code können Sie try...except-Blöcke für Bibliotheksvorgänge verwenden.

Weitere Informationen zu den Arten von Ausnahmen, die ausgelöst werden können, finden Sie in der Dokumentation für den betreffenden Vorgang.

Protokollierung

Die neuesten Azure-Bibliotheken verwenden die Python-Standardbibliothek logging , um die Protokollausgabe zu generieren. Sie können die Protokollierungsebene für einzelne Bibliotheken, Bibliothekengruppen oder alle Bibliotheken festlegen. Nachdem Sie einen Protokollierungsstreamhandler registriert haben, können Sie die Protokollierung für ein bestimmtes Clientobjekt oder einen bestimmten Vorgang aktivieren. Weitere Informationen finden Sie unter Protokollierung in den Azure-Bibliotheken.

Proxykonfiguration

Um einen Proxy anzugeben, können Sie Umgebungsvariablen oder optionale Argumente verwenden. Weitere Informationen finden Sie unter Konfigurieren von Proxys.

Optionale Argumente für Clientobjekte und -methoden

In der Bibliotheksdokumentation sieht man oft ein **kwargs oder **operation_config Argument in der Signatur eines Clientobjektkonstruktors oder einer bestimmten Vorgangsmethode. Diese Platzhalter geben an, dass das betreffende Objekt oder die betreffende Methode andere benannte Argumente unterstützen kann. In der Regel gibt die Referenzdokumentation die spezifischen Argumente an, die Sie verwenden können. Es gibt auch einige allgemeine Argumente, die häufig unterstützt werden, wie in den folgenden Abschnitten beschrieben.

Argumente für Bibliotheken basierend auf azure.core

Diese Argumente gelten für diese Bibliotheken, die unter Python - New Libraries aufgeführt sind. Hier ist beispielsweise eine Teilmenge der Schlüsselwortargumente für azure-core. Eine vollständige Liste finden Sie im GitHub README für Azure Core.

Name	Typ	Standard	BESCHREIBUNG
logging_enable	Boolesch	Falsch	Aktiviert die Protokollierung. Weitere Informationen finden Sie unter Protokollierung in den Azure-Bibliotheken.
Vertretungen	Wörterbuch	{}	Proxyserver-URLs. Weitere Informationen finden Sie unter Konfigurieren von Proxys.
use_env_settings	Boolesch	Richtig	Wenn True, ermöglicht die Verwendung von `HTTP_PROXY` Variablen und `HTTPS_PROXY` Umgebungsvariablen für Proxys. Wenn False, werden die Umgebungsvariablen ignoriert. Weitere Informationen finden Sie unter Konfigurieren von Proxys.
connection_timeout	INT	300	Das Zeitlimit in Sekunden für die Herstellung einer Verbindung zu Azure REST-API-Endpunkten.
read_timeout	INT	300	Das Timeout in Sekunden zum Abschließen eines Azure REST-API-Vorgangs (d. a. Warten auf eine Antwort).
retry_total	INT	10	Die Anzahl der zulässigen Wiederholungsversuche für REST-API-Aufrufe. Verwenden Sie `retry_total=0`, um Wiederholungsversuche zu deaktivieren.
retry_mode	Enumeration	exponentiell	Wendet Wiederholungsversuche auf lineare oder exponentielle Weise an. Bei „single“ werden Wiederholungsversuche in regelmäßigen Intervallen ausgeführt. Bei "exponentiell" dauert jeder Wiederholungsversuch doppelt so lange wie der vorherige.

Einzelne Bibliotheken sind nicht verpflichtet, eines dieser Argumente zu unterstützen, daher finden Sie immer die Referenzdokumentation für jede Bibliothek, um genaue Details zu erhalten. Außerdem kann jede Bibliothek andere Argumente unterstützen. Zum Beispiel finden Sie spezifische Schlüsselwortargumente für Blob-Speicher im GitHub-README für azure-storage-blob.

Inline-JSON-Muster für Objektargumente

Viele Vorgänge in den Azure-Bibliotheken ermöglichen es Ihnen, Objektargumente entweder als diskrete Objekte oder als Inline-JSON auszudrücken.

Angenommen, Sie haben ein ResourceManagementClient Objekt, über das Sie eine Ressourcengruppe mit der zugehörigen create_or_update Methode erstellen. Das zweite Argument für diese Methode ist vom Typ ResourceGroup.

Um die create_or_update Methode aufzurufen, können Sie eine diskrete Instanz von ResourceGroup direkt mit den erforderlichen Argumenten erstellen (location in diesem Fall):

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

Alternativ können Sie dieselben Parameter wie inline JSON übergeben:

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

Wenn Sie inline JSON verwenden, konvertieren die Azure-Bibliotheken die Inline-JSON automatisch in den entsprechenden Objekttyp für das betreffende Argument.

Objekte können auch geschachtelte Objektargumente enthalten, in diesem Fall können Sie auch geschachtelte JSON verwenden.

Angenommen, Sie haben eine Instanz des KeyVaultManagementClient Objekts und rufen dessen create_or_updateInstanz auf. In diesem Fall ist das dritte Argument vom Typ VaultCreateOrUpdateParameters, das selbst ein Argument vom Typ VaultPropertiesenthält. VaultPropertiesenthält wiederum Objektargumente vom Typ Sku und list[AccessPolicyEntry]. A Sku enthält ein SkuName Objekt, und jedes AccessPolicyEntry enthält ein Permissions Objekt.

Zum Aufrufen begin_create_or_update mit eingebetteten Objekten verwenden Sie Code wie die folgende (vorausgesetzt tenant_id, object_idund LOCATION sind bereits definiert). Sie können auch die erforderlichen Objekte vor dem Funktionsaufruf erstellen.

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

Derselbe Aufruf mit Inline-JSON wird wie folgt angezeigt:

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

Da beide Formulare gleichwertig sind, können Sie auswählen, welche Option Sie bevorzugen, und sie sogar miteinander mischen. (Der vollständige Code für diese Beispiele finden Sie auf GitHub.)

Wenn Ihr JSON nicht ordnungsgemäß gebildet wird, erhalten Sie in der Regel den Fehler „DeserializationError: Deserialisierung in Objekt nicht möglich: Typ, AttributeError: ‚str‘-Objekt hat kein Attribut ‚get‘“. Eine häufige Ursache für diesen Fehler ist, dass Sie eine einzelne Zeichenfolge für eine Eigenschaft bereitstellen, wenn die Bibliothek ein geschachteltes JSON-Objekt erwartet. Beispielsweise generiert die Verwendung 'sku': 'standard' im vorherigen Beispiel diesen Fehler, da der sku Parameter ein Sku Objekt ist, das inline-Objekt-JSON erwartet, in diesem Fall {'name': 'standard'}, der dem erwarteten SkuName Typ zugeordnet ist.

Nächste Schritte

Da Sie nun die allgemeinen Muster für die Verwendung der Azure-Bibliotheken für Python kennen, nutzen Sie die folgenden eigenständigen Beispiele, um spezifische Szenarien zur Verwaltung und Nutzung der Clientbibliotheken zu erkunden. Sie können diese Beispiele in beliebiger Reihenfolge ausprobieren, da sie nicht sequenziell oder interdependent sind.

Freigeben über