Aracılığıyla paylaş

Python kullanım desenleri için Azure kitaplıkları

Python için Azure SDK, Python SDK paket dizininde listelenen birçok bağımsız kitaplıklardan oluşur.

Tüm kitaplıklar, yükleme ve nesne bağımsız değişkenleri için satır içi JSON kullanımı gibi bazı ortak özellikleri ve kullanım desenlerini paylaşır.

Yerel geliştirme ortamınızı ayarlama

Henüz yapmadıysanız, bu kodu çalıştırabileceğiniz bir ortam ayarlayabilirsiniz. Aşağıda bazı seçenekleri görebilirsiniz:

  • venv veya seçtiğiniz aracı kullanarak bir Python sanal ortamı yapılandırın. Sanal ortamı kullanmaya başlamak için etkinleştirmeyi unutmayın. Python'ı yüklemek için bkz. Python'ı yükleme.

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

  • Conda ortamı kullanın. Conda'yı yüklemek için bkz. Miniconda'yı yükleme.

  • Visual Studio Code veya GitHub Codespaces'taGeliştirme Kapsayıcısı kullanın.

Kütüphane kurulumu

Python ortam yönetim aracınıza karşılık gelen pip veya conda yükleme yöntemini seçin.

Belirli bir kitaplık paketini yüklemek için kullanın 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 geçerli Python ortamınızdaki bir kitaplığın en son sürümünü alır.

Ayrıca, kitaplıkları kaldırmak ve önizleme sürümleri de dahil olmak üzere belirli sürümleri yüklemek için de kullanabilirsiniz pip . Daha fazla bilgi için bkz. Python için Azure kitaplık paketlerini yükleme.

Zaman uyumsuz işlemler

Asenkron kütüphaneler

Birçok istemci ve yönetim kitaplığı zaman uyumsuz sürümler (.aio) sağlar. Kitaplık asyncio Python 3.4'ten beri kullanılabilir ve async/await anahtar sözcükleri Python 3.5'te kullanıma sunulmuştur. Kitaplıkların zaman uyumsuz sürümleri Python 3.5 ve üstü sürümlerle kullanılmak üzere tasarlanmıştır.

Zaman uyumsuz sürümlere sahip Azure Python SDK kitaplıklarına örnek olarak şunlar verilebilir: azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio ve azure.mgmt.compute.aio.

Bu kütüphanelerin çalışabilmesi için aiohttp gibi bir asenkron aktarım gerekir. Kütüphane azure-core, AioHttpTransport zaman uyumsuz kütüphaneler tarafından kullanılan bir asenkron taşıma sağlar, bu nedenle onu ayrı olarak yüklemeniz aiohttp gerekmeyebilir.

Aşağıdaki kod, Azure Blob Depolama kitaplığının zaman uyumsuz sürümü için nasıl istemci oluşturulacağını gösteren bir python dosyasının nasıl oluşturulacağını gösterir:

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

Tam örnek use_blob_auth_async.py GitHub'dadır. Bu kodun zaman uyumlu sürümü için Örnek: Blobu karşıya yükleme bölümüne bakın.

Uzun süreli işlemler

Çağırdığınız bazı yönetim işlemleri (örneğin ComputeManagementClient.virtual_machines.begin_create_or_update ve WebAppsClient.web_apps.begin_create_or_update), belirli uzun süre çalışan işlemler için bir poller geri döner, burada LROPoller[<type>] söz konusu işleme özgüdür.

Uyarı

Bir kitaplıktaki yöntem adlarında sürümüne ve azure.core tabanlı olup olmadığına bağlı olarak farklılıklar fark edebilirsiniz. Genellikle azure.core tabanlı olmayan eski kitaplıklar create_or_update gibi adlar kullanır. azure.core tabanlı kitaplıklar, uzun yoklama işlemleri olduğunu daha iyi belirtmek için yöntem adlarına ön eki ekler begin_ . Eski kodu daha yeni bir azure.core tabanlı kitaplığa geçirmek genellikle yöntem adlarına ön ek eklemek begin_ anlamına gelir. Yöntem imzalarının çoğu aynı kalır.

LROPoller Dönüş türü, işlemin zaman uyumsuz olduğu anlamına gelir. Buna göre, işlemin bitmesini beklemek ve sonucunu almak için bu poller'ın result yöntemini çağırmanız gerekir.

Örnek: Bir web uygulaması oluşturma ve dağıtma bölümünden alınan aşağıdaki kod, bir sonucu beklemek için poller kullanma örneğini gösterir:



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

Bu durumda, begin_create_or_update'nin geri dönüş değeri AzureOperationPoller[Site] türündedir, yani poller.result()'nin dönüş değeri bir Site nesnesidir.

Özel durumlar

Genel olarak Azure kitaplıkları, Azure REST API'ye yapılan başarısız HTTP istekleri de dahil olmak üzere işlemlerin beklendiği gibi gerçekleştirilemediği durumlarda özel durumlar oluşturur. Uygulama kodu için kitaplık işlemleri etrafında try...except blokları kullanabilirsiniz.

Oluşturulabilecek özel durumların türü hakkında daha fazla bilgi için, söz konusu işlemin belgelerine bakın.

Ağaç kesimi

En son Azure kitaplıkları, günlük çıktısı oluşturmak için Python standart logging kitaplığını kullanır. Tek tek kitaplıklar, kitaplık grupları veya tüm kitaplıklar için günlük düzeyini ayarlayabilirsiniz. Bir günlük akış işleyicisini kaydettikten sonra, belirli bir istemci nesnesi veya belirli bir işlem için günlüğe kaydetmeyi etkinleştirebilirsiniz. Daha fazla bilgi için bkz. Azure kütüphanelerinde kayıt tutma.

Proxy yapılandırması

Ara sunucu belirtmek için ortam değişkenlerini veya isteğe bağlı bağımsız değişkenleri kullanabilirsiniz. Daha fazla bilgi için bkz. Proxy'leri yapılandırma.

İstemci nesneleri ve yöntemleri için isteğe bağlı bağımsız değişkenler

Kitaplık referans belgelerinde, genellikle bir istemci nesne oluşturucusunun imzasında veya belirli bir işlem yönteminde **kwargs veya **operation_config bağımsız değişkeni görürsünüz. Yer tutucular, söz konusu nesnenin veya yöntemin diğer adlandırılmış bağımsız değişkenleri destekleyebileceğini gösterir. Genellikle, başvuru belgeleri kullanabileceğiniz parametreleri belirtir. Ayrıca, genellikle aşağıdaki bölümlerde açıklandığı gibi desteklenen bazı genel argümanlar da vardır.

azure.core tabanlı kitaplıklar için argümanlar

Bu argümanlar Python - Yeni Kitaplıklar'da listelenen kütüphaneler için geçerlidir. Örneğin, azure-core için anahtar sözcük bağımsız değişkenlerinin bir alt kümesi yer almaktadır. Tam liste için bkz. azure-core için GitHub README.

İsim Türü Varsayılan Açıklama
günlüğü_aktifleştir Boole Yanlış Günlüğe kaydetmeyi etkinleştirir. Daha fazla bilgi için bkz. Azure kütüphanelerinde kayıt tutma.
Proxyler Dict {} Ara sunucu URL'leri. Daha fazla bilgi için bkz. Proxy'leri yapılandırma.
çevre_ayarlarını_kullan Boole Doğru True ise proxy'ler HTTP_PROXY için ve HTTPS_PROXY ortam değişkenlerinin kullanılmasına izin verir. False ise ortam değişkenleri yoksayılır. Daha fazla bilgi için bkz. Proxy'leri yapılandırma.
bağlantı zaman aşımı Int 300 Azure REST API uç noktalarına bağlantı oluşturmak için bağlantı zaman aşımı süresi saniye cinsinden.
okuma zaman aşımı Int 300 Bir Azure REST API işlemini tamamlama süresi için saniyeler cinsinden belirlenen zaman sınırı (yani yanıt bekleme süresi).
toplam yeniden deneme Int 10 REST API çağrıları için izin verilebilen yeniden deneme denemelerinin sayısı. Yeniden denemeleri devre dışı bırakmak için kullanın retry_total=0 .
yeniden deneme modu numaralandırma üssel Yeniden deneme zamanlamasını doğrusal veya üstel bir şekilde uygular. 'Tek' ise, yeniden denemeler düzenli aralıklarla yapılır. 'Üstel' ise, her yeniden deneme önceki yeniden denemenin iki katı kadar bekler.

Belirli kütüphaneler bu bağımsız değişkenlerin hiçbirini desteklemek zorunda değiller, bu nedenle detaylı bilgi için her kütüphanenin referans belgelerine her zaman bakın. Ayrıca, her kitaplık diğer bağımsız değişkenleri destekleyebilir. Örneğin, blob depolamaya özgü anahtar sözcük argümanları için azure-storage-blob GitHub README dosyasına bakın.

Nesne bağımsız değişkenleri için satır içi JSON deseni

Azure kitaplıklarındaki birçok işlem, nesne bağımsız değişkenlerini ayrık nesneler veya satır içi JSON olarak ifade etmenizi sağlar.

Örneğin, ResourceManagementClient nesnesiyle create_or_update yöntemi aracılığıyla bir kaynak grubu oluşturduğunuzu varsayalım. Bu yöntemin ikinci bağımsız değişkeni ResourceGroup türündedir.

create_or_update yöntemini çağırmak için, gerekli bağımsız değişkenleri (ResourceGroup bu durumda) ile doğrudan location öğesinin ayrık bir örneğini oluşturabilirsiniz.

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

Alternatif olarak, satır içi JSON ile aynı parametreleri geçirebilirsiniz:

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

Satır içi JSON kullandığınızda, Azure kitaplıkları satır içi JSON'ı otomatik olarak söz konusu bağımsız değişken için uygun nesne türüne dönüştürür.

Nesnelerin iç içe nesne argümanları da olabilir, bu durumda iç içe JSON da kullanabilirsiniz.

Örneğin, bir KeyVaultManagementClient nesnesine sahip olduğunuzu ve onun create_or_update'sini çağırdığınızı varsayalım. Bu durumda, üçüncü bağımsız değişken VaultCreateOrUpdateParameters türündedir ve kendisi VaultProperties türünde bir bağımsız değişken içerir. VaultProperties, sırasıyla Sku ve list[AccessPolicyEntry] türündeki nesne bağımsız değişkenlerini içerir. A Sku bir SkuName nesne içerir ve her AccessPolicyEntry bir nesne içerir Permissions .

Katıştırılmış nesnelerle begin_create_or_update çağırmak için, aşağıdaki gibi bir kod kullanırsınız (tabii ki tenant_id, object_id ve LOCATION zaten tanımlanmış varsayılarak). İşlev çağrısından önce gerekli nesneleri de oluşturabilirsiniz.

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

Satır içi JSON kullanan aynı çağrı aşağıdaki gibi görünür:

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

Her iki form da eşdeğer olduğundan, hangisini tercih ettiğinizi seçebilir ve hatta birbirine karıştırabilirsiniz. (Bu örneklerin tam kodunu GitHub'da bulabilirsiniz.)

JSON'unuz düzgün biçimlendirilmemişse genellikle "Seri Durumdan ÇıkarmaError: Nesne seri durumdan çıkarılamıyor: type, AttributeError: 'str' nesnesinin 'get' özniteliği yok" hatasını alırsınız. Bu hatanın yaygın nedenlerinden biri, kitaplık iç içe JSON nesnesi beklediğinde bir özellik için tek bir dize sağladığınızdır. Örneğin, önceki örnekte 'sku': 'standard' kullanıldığında, bu hata oluşur çünkü sku parametresi, bu durumda Sku ile eşlenen ve beklenen {'name': 'standard'} türüne uygun olan bir satır içi JSON bekleyen SkuName nesnesidir.

Sonraki Adımlar

Python için Azure kitaplıklarını kullanmaya yönelik yaygın desenleri anladığınıza göre, belirli yönetim ve istemci kitaplığı senaryolarını keşfetmek için aşağıdaki tek başına örneklere bakın. Sıralı veya birbirine bağlı olmadığından bu örnekleri istediğiniz sırayla deneyebilirsiniz.

  • Last updated on