Azure-Bibliotheken für Python: Verwendungsmuster

Das Azure SDK für Python besteht aus vielen unabhängigen Bibliotheken. Diese werden im Paketindex für das Python SDK aufgeführt.

Alle Bibliotheken verfügen über bestimmte allgemeine Merkmale und Verwendungsmuster. Hierzu zählen beispielsweise die Installation und die Verwendung von JSON-Inline-Code 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 einige Optionen:

• Konfigurieren Sie eine virtuelle Python-Umgebung mithilfe von venv oder dem Tool Ihrer Wahl. Sie können die virtuelle Umgebung lokal oder in Azure Cloud Shell erstellen und den Code dort ausführen. Stellen Sie sicher, dass Sie die virtuelle Umgebung aktivieren, um sie verwenden zu können.

• Verwenden Sie eine Conda-Umgebung.

• Verwenden Sie einen Entwicklungscontainer in Visual Studio Code oder GitHub Codespaces.

Bibliotheksinstallation

# 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

Asynchrone Vorgänge

Asynchrone Bibliotheken

Viele Client- und Verwaltungsbibliotheken bieten asynchrone Versionen (.aio) an. Die asyncio Bibliothek ist seit Python 3.4 verfügbar, und die async/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 eine asynchrone Übertragung wie z. B. aiohttp, um zu funktionieren. Die azure-core-Bibliothek stellt eine asynchrone Übertragung bereit, AioHttpTransportdie von den asynchronen Bibliotheken verwendet wird.

Der folgende Code zeigt, 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 finden Sie auf GitHub unter use_blob_auth_async.py. Die synchrone Version dieses Codes finden Sie unter Beispiel: Hochladen eines Blobs.

Vorgänge mit langer Ausführung

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

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:

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 von begin_create_or_update vom Typ AzureOperationPoller[Site]. Dies bedeutet, dass der Rückgabewert von poller.result() ein Site-Objekt ist.

Ausnahmen

Im Allgemeinen werden von den Azure-Bibliotheken Ausnahmen ausgelöst, wenn Vorgänge nicht wie vorgesehen ausgeführt werden, einschließlich fehlerhafter HTTP-Anforderungen an die Azure-REST-API. Für App-Code können Sie try...except-Blöcke um Bibliotheksvorgänge herum verwenden.

Weitere Informationen zum Typ der Ausnahmen, die ausgelöst werden können, finden Sie in der Dokumentation zum betreffenden Vorgang.

Logging

Die neuesten Azure-Bibliotheken verwenden die Python-logging-Standardbibliothek, um die Protokollausgabe zu generieren. Sie können den Protokolliergrad für einzelne Bibliotheken, Gruppen von Bibliotheken oder alle Bibliotheken festlegen. Nachdem Sie einen Protokollierungsdatenstrom-Handler 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

Zum Angeben eines Proxys 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 Bibliotheksreferenzdokumentation tritt häufig ein **kwargs- oder **operation_config-Argument in der Signatur eines Clientobjektkonstruktors oder einer bestimmten Vorgangsmethode auf. 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, die auf azure.core basieren

Diese Argumente gelten für die Bibliotheken, die unter Python: Neue Bibliotheken aufgeführt werden. 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.

Einzelne Bibliotheken sind nicht verpflichtet, diese Argumente zu unterstützen, daher sollten Sie sich stets in der Referenzdokumentation für jede Bibliothek über die genauen Details informieren. Außerdem unterstützt jede Bibliothek möglicherweise andere Argumente. Blob Storage-spezifische Schlüsselwortargumente finden Sie zum Beispiel in der GitHub README für azure-storage-blob.

JSON-Inline-Muster für Objektargumente

Bei vielen Vorgängen innerhalb der Azure-Bibliotheken können Objektargumente als diskrete Objekte oder als JSON-Inline-Code ausgedrückt werden.

Angenommen, Sie verfügen über ein ResourceManagementClient-Objekt, über das Sie eine Ressourcengruppe mit seiner create_or_update-Methode erstellen. Das zweite Argument für diese Methode ist vom Typ ResourceGroup.

Zum Aufrufen der create_or_update-Methode können Sie eine diskrete Instanz von ResourceGroup direkt mit den erforderlichen Argumenten erstellen (in diesem Fall location):

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

Alternativ können Sie dieselben Parameter als JSON-Inline-Code übergeben:

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

Wenn Sie Inline-JSON verwenden, wird der JSON-Inline-Code durch die Azure-Bibliotheken automatisch in den für das betreffende Argument geeigneten Objekttyp konvertiert.

Objekte können auch geschachtelte Objektargumente besitzen, und in diesem Fall können Sie dann auch geschachtelten JSON-Code verwenden.

Angenommen, Sie haben beispielsweise eine Instanz des KeyVaultManagementClient-Objekts und rufen seine create_or_update-Methode auf. In diesem Fall ist das dritte Argument vom Typ VaultCreateOrUpdateParameters, das wiederum selbst ein Argument vom Typ VaultProperties enthält. VaultProperties wiederum enthält Objektargumente vom Typ Sku und list[AccessPolicyEntry]. Eine Sku enthält ein SkuName-Objekt, und jeder AccessPolicyEntry enthält ein Permissions-Objekt.

Wenn Sie begin_create_or_update mit eingebetteten Objekten aufrufen möchten, müssen Sie Code wie den folgenden verwenden (vorausgesetzt, tenant_id, object_id und LOCATION sind bereits definiert). Die erforderlichen Objekte können auch vor dem Funktionsaufruf erstellt werden.

# 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 unter Verwendung von JSON-Inline-Code sieht wie folgt aus:

# 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 Formen äquivalent sind, können Sie die von Ihnen bevorzugte Form und sogar eine Kombination verwenden. (Den vollständigen Code für diese Beispiele finden Sie auf GitHub.)

Wenn Ihr JSON-Code nicht ordnungsgemäß formatiert ist, erhalten Sie in der Regel den Fehler „DeserializationError: Objekt kann nicht deserialisiert werden: Typ, AttributeError: ‚str‘-Objekt weist kein Attribut ‚get‘ auf". Eine häufige Ursache für diesen Fehler ist die Angabe einer einzelnen Zeichenfolge für eine Eigenschaft, obwohl von der Bibliothek ein geschachteltes JSON-Objekt erwartet wird. Wenn Sie z. B. im vorherigen Beispiel 'sku': 'standard' verwenden, generiert dies diesen Fehler, weil der Parameter sku ein Sku-Objekt ist, das JSON-Inline-Objektcode erwartet, in diesem Fall {'name': 'standard'}, der dem erwarteten SkuName-Typ entspricht.

Nächste Schritte

Nachdem Sie nun mit den allgemeinen Mustern für die Verwendung der Azure-Bibliotheken für Python vertraut sind, können Sie sich als Nächstes anhand der folgenden eigenständigen Beispiele mit spezifischen Szenarien für die Verwaltung und für Clientbibliotheken beschäftigen. Da diese Beispiele nicht sequenziell oder voneinander abhängig sind, gibt es keine vorgegebene Reihenfolge.

• Beispiel: Erstellen einer Ressourcengruppe

• Beispiel: Verwenden von Azure Storage

• Beispiel: Erstellen einer Web-App und Bereitstellen von Code

• Beispiel: Erstellen und Abfragen einer Datenbank

• Beispiel: Erstellen eines virtuellen Computers

• Verwenden verwalteter Azure-Datenträger mit den Azure-Bibliotheken (SDK) für Python

• Kurze Umfrage zum Azure SDK für Python