Azure-Bibliotheken für Python-Verwendungsmuster

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, richten Sie eine Umgebung ein, 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.

  • Bash
  • 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)
  

• 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.

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

# 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

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, AioHttpTransportden die asynchronen Bibliotheken verwenden, 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.

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 verwenden Sie try...except-Blöcke um Bibliotheksoperationen.

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

Verwenden Sie Zum Angeben eines Proxys Umgebungsvariablen oder optionale Argumente. 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 Referenzdokumentation werden in der Regel die spezifischen Argumente aufgeführt, die Sie verwenden können. In den folgenden Abschnitten werden einige allgemeine Argumente beschrieben, die häufig unterstützt werden.

Argumente für Bibliotheken basierend auf azure.core

Diese Argumente gelten für die 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.

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 unterstützt jede Bibliothek möglicherweise andere Argumente. 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 innerhalb der Azure-Bibliotheken akzeptieren Objektargumente entweder als diskrete Objekte oder inline-JSON.

Angenommen, Sie haben ein ResourceManagementClient Objekt, über das Sie eine Ressourcengruppe mithilfe 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.

• 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 von Azure Managed Disks mit virtuellen Computern

• Eine kurze Umfrage zum Azure SDK für Python abschließen