Azure-bibliotheken voor Python-gebruikspatronen

Artikel
04/11/2024

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.

De 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. U kunt de virtuele omgeving lokaal of in Azure Cloud Shell maken en daar de code uitvoeren. Zorg ervoor dat u de virtuele omgeving activeert om deze te gaan gebruiken.
Gebruik een Conda-omgeving.
Gebruik een Dev-container in Visual Studio Code of GitHub Codespaces.

Als u een specifiek bibliotheekpakket wilt installeren, gebruikt u 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

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.

Als u een specifiek bibliotheekpakket wilt installeren in een Conda-omgeving, gebruikt u conda install:

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

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

conda install haalt de nieuwste versie van een pakket op in uw huidige Conda-omgeving.

Zie Azure-bibliotheekpakketten installeren voor Python voor meer informatie, waaronder het verwijderen van pakketten of het installeren van specifieke versies.

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.

De volgende code 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 WebSiteManagementClient.web_apps.begin_create_or_update retourneren van een poller voor langdurige bewerkingen, LROPoller[<type>]waarbij <type> dit specifiek is voor de betreffende bewerking.

Notitie

Mogelijk ziet u verschillen in methodenamen in een bibliotheek, wat te wijten is aan versieverschillen. 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 methode van result 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:

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 app-code kunt u blokken rond bibliotheekbewerkingen gebruiken try...except .

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

Logboekregistratie

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.

Name	Type	Default	Beschrijving
logging_enable	bool	Onwaar	Schakelt logboekregistratie in. Zie Logboekregistratie in de Azure-bibliotheken voor meer informatie.
proxy's	Dict	{}	URL's van proxyserver. Zie Proxy's configureren voor meer informatie.
use_env_settings	bool	Waar	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	300	De time-out in seconden voor het maken van een verbinding met Azure REST API-eindpunten.
read_timeout	int	300	De time-out in seconden voor het voltooien van een Azure REST API-bewerking (dat wil gezegd, wachten op een antwoord).
retry_total	int	10	Het aantal toegestane nieuwe pogingen voor REST API-aanroepen. Gebruik `retry_total=0` dit om nieuwe pogingen uit te schakelen.
retry_mode	enum	exponentieel	Tijdsinstellingen voor opnieuw proberen worden toegepast op een lineaire of exponentiële manier. Als 'enkel', worden er regelmatig nieuwe pogingen gedaan. Als 'exponentieel' wordt geprobeerd, wacht elke nieuwe poging twee keer zo lang als de vorige nieuwe poging.

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 een discrete instantie ResourceGroup van rechtstreeks met de vereiste argumenten maken (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 de bijbehorende methode 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 goed is gevormd, krijgt u meestal de foutmelding 'DeserializationError: Kan object niet deserialiseren: type, AttributeError: 'str' object heeft geen kenmerk '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 in het vorige voorbeeld gebruikt, 'sku': 'standard' wordt deze fout gegenereerd omdat de sku parameter een Sku object is dat JSON inlineobject verwacht, in dit geval {'name': 'standard'}, die 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.

Delen via