Delen via

Azure-bibliotheken voor Python-gebruikspatronen

De Azure SDK voor Python bestaat uit veel onafhankelijke bibliotheken, die worden vermeld in de Python SDK-pakketindex.

Alle bibliotheken delen bepaalde algemene kenmerken en gebruikspatronen, zoals de installatie en het gebruik van inline-JSON voor objectargumenten.

Uw lokale ontwikkelomgeving instellen

Als u dat nog niet hebt gedaan, kunt u een omgeving instellen waarin u deze code kunt uitvoeren. Hieronder volgen een aantal opties:

  • Configureer een virtuele Python-omgeving met behulp van venv of uw hulpprogramma naar keuze. Als u de virtuele omgeving wilt gaan gebruiken, moet u deze activeren. Om Python te installeren, raadpleeg Python installeren.

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

  • Gebruik een Conda-omgeving. Zie Miniconda installeren om Conda te installeren.

  • Gebruik een Dev Container in Visual Studio Code of GitHub Codespaces.

Bibliotheekinstallatie

Kies de installatiemethode die overeenkomt met uw Python-hulpprogramma voor omgevingsbeheer, pip of conda.

Als u een specifiek bibliotheekpakket wilt installeren, gebruikt u pip install:

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 haalt de nieuwste versie van een bibliotheek op in uw huidige Python-omgeving.

U kunt ook pip bibliotheken verwijderen en specifieke versies installeren, waaronder preview-versies. Zie Azure-bibliotheekpakketten voor Python installeren voor meer informatie.

Asynchrone bewerkingen

Asynchrone bibliotheken

Veel client- en beheerbibliotheken bieden asynchrone versies (.aio). De asyncio bibliotheek is beschikbaar sinds Python 3.4 en de trefwoorden async/await zijn geïntroduceerd in Python 3.5. De asynchrone versies van de bibliotheken zijn bedoeld voor gebruik met Python 3.5 en hoger.

Voorbeelden van Azure Python SDK-bibliotheken met asynchrone versies zijn : azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio en azure.mgmt.compute.aio.

Deze bibliotheken hebben een asynchroon transport nodig, bijvoorbeeld aiohttp om te kunnen werken. De azure-core bibliotheek biedt een asynchroon transport, AioHttpTransportdat wordt gebruikt door de asynchrone bibliotheken, zodat u mogelijk niet afzonderlijk hoeft te installeren aiohttp .

De volgende code laat zien hoe u een Python-bestand maakt dat laat zien hoe u een client maakt voor de asynchrone versie van de Azure Blob Storage-bibliotheek:

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

Het volledige voorbeeld bevindt zich op GitHub op use_blob_auth_async.py. Zie Voorbeeld: Een blob uploaden voor de synchrone versie van deze code.

Langlopende bewerkingen

Sommige beheerbewerkingen die u aanroept (zoals ComputeManagementClient.virtual_machines.begin_create_or_update en WebAppsClient.web_apps.begin_create_or_update) retourneren een poller voor langdurige bewerkingen, LROPoller[<type>]waarbij dit <type> specifiek is voor de betreffende bewerking.

Opmerking

Mogelijk merkt u verschillen in methodenamen in een bibliotheek, afhankelijk van de versie en of deze is gebaseerd op azure.core. Oudere bibliotheken die niet zijn gebaseerd op azure.core, gebruiken doorgaans namen als create_or_update. Bibliotheken op basis van azure.core voegen het begin_ voorvoegsel toe aan methodenamen om beter aan te geven dat ze lange pollingbewerkingen zijn. Het migreren van oude code naar een nieuwere bibliotheek op basis van azure.core betekent doorgaans het toevoegen van het begin_ voorvoegsel aan methodenamen, omdat de meeste methodehandtekeningen hetzelfde blijven.

Het LROPoller retourtype betekent dat de bewerking asynchroon is. Daarom moet u de result-methode van die poller aanroepen om te wachten tot de bewerking is voltooid en het resultaat ervan te verkrijgen.

De volgende code, afkomstig uit voorbeeld: Een web-app maken en implementeren, toont een voorbeeld van het gebruik van de poller om te wachten op een resultaat:



# 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 dit geval is de retourwaarde begin_create_or_update van het type AzureOperationPoller[Site], wat betekent dat de retourwaarde poller.result() een Site-object is.

Uitzonderingen

Over het algemeen genereren de Azure-bibliotheken uitzonderingen wanneer bewerkingen niet naar behoren worden uitgevoerd, inclusief mislukte HTTP-aanvragen voor de Azure REST API. Voor applicatiecode kunt u try...except blokken om bibliotheekbewerkingen heen gebruiken.

Zie de documentatie voor de betreffende bewerking voor meer informatie over het type uitzonderingen dat kan worden gegenereerd.

Loggen

De meest recente Azure-bibliotheken maken gebruik van de standaardbibliotheek logging van Python om logboekuitvoer te genereren. U kunt het logboekregistratieniveau instellen voor afzonderlijke bibliotheken, groepen bibliotheken of alle bibliotheken. Zodra u een handler voor logboekregistratiestreams registreert, kunt u logboekregistratie inschakelen voor een specifiek clientobject of een specifieke bewerking. Zie Logboekregistratie in de Azure-bibliotheken voor meer informatie.

Proxyconfiguratie

Als u een proxy wilt opgeven, kunt u omgevingsvariabelen of optionele argumenten gebruiken. Zie Proxy's configureren voor meer informatie.

Optionele argumenten voor clientobjecten en -methoden

In de bibliotheekreferentiedocumentatie ziet u vaak een **kwargs of **operation_config argument in de handtekening van een clientobjectconstructor of een specifieke bewerkingsmethode. Deze tijdelijke aanduidingen geven aan dat het betreffende object of de betreffende methode andere benoemde argumenten kan ondersteunen. Normaal gesproken geeft de referentiedocumentatie de specifieke argumenten aan die u kunt gebruiken. Er zijn ook enkele algemene argumenten die vaak worden ondersteund, zoals beschreven in de volgende secties.

Argumenten voor bibliotheken op basis van azure.core

Deze argumenten zijn van toepassing op die bibliotheken die worden vermeld in Python - Nieuwe bibliotheken. Hier ziet u bijvoorbeeld een subset van de trefwoordargumenten voor azure-core. Zie de GitHub README voor azure-core voor een volledige lijst.

Naam Typologie Verstek Beschrijving
logging inschakelen Bool Onwaar Schakelt logboekregistratie in. Zie Logboekregistratie in de Azure-bibliotheken voor meer informatie.
Proxies Woordenboek {} URLs van proxyservers. Zie Proxy's configureren voor meer informatie.
gebruik_omgevingsinstellingen Bool Klopt Indien waar, staat u het gebruik van HTTP_PROXY en HTTPS_PROXY omgevingsvariabelen voor proxy's toe. Als onwaar, worden de omgevingsvariabelen genegeerd. Zie Proxy's configureren voor meer informatie.
connection_timeout int (integer) 300 De time-out in seconden voor het maken van een verbinding met Azure REST API-eindpunten.
leestijdlimiet int (integer) 300 De time-out in seconden voor het voltooien van een Azure REST API-bewerking (dat wil gezegd, wachten op een antwoord).
herhaal_totaal int (integer) 10 Het aantal toegestane nieuwe pogingen voor REST API-aanroepen. Gebruik retry_total=0 om nieuwe pogingen uit te schakelen.
herhaalmodus enumeratie exponentieel Tijdsinstellingen voor opnieuw proberen worden toegepast op een lineaire of exponentiële manier. Als 'enkel', worden er regelmatig nieuwe pogingen gedaan. Als er voor 'exponentieel' wordt gekozen, wacht elke poging twee keer zo lang als de vorige.

Afzonderlijke bibliotheken zijn niet verplicht om een van deze argumenten te ondersteunen, dus raadpleeg altijd de referentiedocumentatie voor elke bibliotheek voor exacte details. Bovendien kan elke bibliotheek andere argumenten ondersteunen. Zie bijvoorbeeld de GitHub README voor azure-storage-blob voor specifieke trefwoordargumenten voor blobopslag.

Inline JSON-patroon voor objectargumenten

Met veel bewerkingen in de Azure-bibliotheken kunt u objectargumenten uitdrukken als discrete objecten of als inline-JSON.

Stel dat u een ResourceManagementClient object hebt waarmee u een resourcegroep maakt met de create_or_update bijbehorende methode. Het tweede argument voor deze methode is van het type ResourceGroup.

Als u de create_or_update-methode wilt aanroepen, kunt u direct een discrete instantie van ResourceGroup maken met de vereiste argumenten (location in dit geval):

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

U kunt ook dezelfde parameters doorgeven als inline JSON:

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

Wanneer u inline JSON gebruikt, converteren de Azure-bibliotheken de inline-JSON automatisch naar het juiste objecttype voor het betreffende argument.

Objecten kunnen ook geneste objectargumenten hebben. In dat geval kunt u ook geneste JSON gebruiken.

Stel dat u een exemplaar van het KeyVaultManagementClient object hebt en het object aanroept create_or_update. In dit geval is het derde argument van het type VaultCreateOrUpdateParameters, dat zelf een argument van het type VaultPropertiesbevat. VaultPropertiesbevat op zijn beurt objectargumenten van het type Sku en list[AccessPolicyEntry]. Een Sku bevat een SkuName object en elk AccessPolicyEntry object bevat een Permissions object.

Als u met ingesloten objecten wilt aanroepenbegin_create_or_update, gebruikt u code zoals het volgende (ervan uitgaande tenant_idobject_id, en LOCATION zijn al gedefinieerd). U kunt ook de benodigde objecten maken vóór de functie-aanroep.

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

Dezelfde aanroep met inline JSON wordt als volgt weergegeven:

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

Omdat beide formulieren gelijkwaardig zijn, kunt u kiezen wat u wilt en zelfs intermixen. (De volledige code voor deze voorbeelden vindt u op GitHub.)

Als uw JSON niet correct is gevormd, krijgt u meestal de foutmelding: 'DeserializationError: Kan object niet deserialiseren: type, AttributeError: 'str' object heeft geen attribuut 'get'. Een veelvoorkomende oorzaak van deze fout is dat u één tekenreeks voor een eigenschap opgeeft wanneer in de bibliotheek een geneste JSON-object wordt verwacht. Als u bijvoorbeeld 'sku': 'standard' gebruikt in het vorige voorbeeld, wordt deze fout gegenereerd omdat de parameter sku een Sku-object is dat een inline JSON-object verwacht, in dit geval {'name': 'standard'}, dat is toegewezen aan het verwachte SkuName-type.

Volgende stappen

Nu u inzicht hebt in de algemene patronen voor het gebruik van de Azure-bibliotheken voor Python, raadpleegt u de volgende zelfstandige voorbeelden om specifieke beheer- en clientbibliotheekscenario's te verkennen. U kunt deze voorbeelden in elke volgorde proberen, omdat ze niet opeenvolgend of afhankelijk zijn.