Azure-Bibliotheken für Python: Verwendungsmuster

  • Artikel

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

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:

Bibliotheksinstallation

Verwenden Sie zum Installieren eines bestimmten Bibliothekspakets den Befehl 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

Von pip install wird die neueste Version einer Bibliothek in Ihrer aktuellen Python-Umgebung abgerufen.

pip kann auch zum Deinstallieren von Bibliotheken sowie zum Installieren bestimmter Versionen (einschließlich Vorschauversionen) verwendet werden. Weitere Informationen 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 async/await Schlüsselwort (keyword) 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, z aiohttp . B. zum Arbeiten. Die azure-core Bibliothek stellt einen asynchronen Transport bereit, AioHttpTransportder 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 befindet sich auf GitHub bei 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 ComputeManagementClient.virtual_machines.begin_create_or_update . B. einen WebSiteManagementClient.web_apps.begin_create_or_update Poller für vorgänge mit langer Ausführung zurückgeben, LROPoller[<type>]wobei <type> der betreffende Vorgang spezifisch ist).

Hinweis

Möglicherweise stellen Sie Unterschiede bei methodennamen in einer Bibliothek fest, was auf Versionsunterschiede zurückzuführen ist. Ä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 begin_ Präfix zu Methodennamen hinzu, um besser anzugeben, dass sie lange Abrufvorgänge sind. Wenn Sie alten Code zu einer neueren, auf „azure.core“ basierenden Bibliothek migrieren möchten, müssen Sie in der Regel den Methodennamen das Präfix begin_ hinzufügen.

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 begin_create_or_update vom Typ AzureOperationPoller[Site], was bedeutet, dass der Rückgabewert 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 Blöcke für Bibliotheksvorgänge verwenden try...except .

Weitere Informationen zu den Arten von Ausnahmen, die ausgelöst werden können, finden Sie in der Dokumentation für den 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

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 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üsselwort (keyword) Argumente für azure-core. Eine vollständige Liste finden Sie im GitHub README für Azure Core.

Name type Standard Beschreibung
logging_enable bool False Aktiviert die Protokollierung. Weitere Informationen finden Sie unter Protokollierung in den Azure-Bibliotheken.
Proxys dict {} Proxyserver-URLs. Weitere Informationen finden Sie unter Konfigurieren von Proxys.
use_env_settings bool True Wenn TRUE, ist die Verwendung von HTTP_PROXY- und HTTPS_PROXY-Umgebungsvariablen für Proxys zulässig. Wenn FALSE, werden Umgebungsvariablen ignoriert. Weitere Informationen finden Sie unter Konfigurieren von Proxys.
connection_timeout int 300 Das Timeout in Sekunden für das Herstellen einer Verbindung mit Azure-REST-API-Endpunkten.
read_timeout int 300 Das Timeout (in Sekunden) für das Abschließen eines Azure-REST-API-Vorgangs (das heißt, das Warten auf eine Antwort).
retry_total INT 10 Die Anzahl zulässiger Wiederholungsversuche für REST-API-Aufrufe. Verwenden Sie retry_total=0, um Wiederholungsversuche zu deaktivieren.
retry_mode enum exponential Wendet Wiederholungsversuche auf lineare oder exponentielle Weise an. Bei „single“ werden Wiederholungsversuche in regelmäßigen Intervallen ausgeführt. Bei „exponential“ wartet jeder Wiederholungsversuch doppelt so lange wie der vorherige Wiederholungsversuch.

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. For example, for blob storage specific Schlüsselwort (keyword) arguments, see the GitHub README for 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 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 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, konvertieren die Azure-Bibliotheken die Inline-JSON automatisch in den entsprechenden Objekttyp für das betreffende Argument.

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.

Zum Aufrufen begin_create_or_update mit eingebetteten Objekten verwenden Sie Code wie die folgende (vorausgesetzt tenant_id, object_idund 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 nicht ordnungsgemäß gebildet wird, erhalten Sie in der Regel den Fehler "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'". 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. Sie können diese Beispiele in beliebiger Reihenfolge ausprobieren, da sie nicht sequenziell oder interdependent sind.