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

  • Makale

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ı kurun

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

  • Python sanal ortamını yapılandırma. Sanal ortamı yerel olarak veya Azure Cloud Shell'de oluşturabilir ve kodu orada çalıştırabilirsiniz. Kullanmaya başlamak için sanal ortamı etkinleştirdiğinizden emin olun.

  • Conda ortamı kullanın.

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

Kitaplık yüklemesi

Belirli bir kitaplık paketini yüklemek için kullanın 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 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

Zaman uyumsuz kitaplıklar

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ümlerinin Python 3.5 ve üzeri sürümlerle kullanılması amaçlanmış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 kitaplıkların çalışması için zaman aiohttp uyumsuz bir aktarım gerekir. Kitaplık azure-core , AioHttpTransportzaman uyumsuz kitaplıklar tarafından kullanılan bir zaman uyumsuz aktarım sağlar.

Aşağıdaki kod, Azure Blob Depolama kitaplığının zaman uyumsuz sürümü için nasıl istemci 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 bkz . Örnek: Blobu karşıya yükleme.

Uzun süre çalışan işlemler

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

Not

Bir kitaplıktaki yöntem adlarında, sürüm farklılıkları nedeniyle farklılıklar fark edebilirsiniz. azure.core tabanlı olmayan eski kitaplıklarda genellikle gibi create_or_updateadlar kullanılı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:

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, değerinin dönüş değeri begin_create_or_update türündedir AzureOperationPoller[Site], yani değerinin dönüş değeri poller.result() 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şlemlerinin etrafındaki blokları kullanabilirsiniz try...except .

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

Günlük Kaydı

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 kitaplıklarında günlüğe kaydetme.

Ara sunucu 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 başvurusu belgelerinde genellikle bir istemci nesne oluşturucusunun veya belirli bir **kwargs işlem yönteminin imzasında bir veya **operation_config bağımsız değişkeni görürsünüz. Bu yer tutucular, söz konusu nesnenin veya yöntemin diğer adlandırılmış bağımsız değişkenleri destekleyeebileceğini gösterir. Genellikle, başvuru belgeleri kullanabileceğiniz belirli bağımsız değişkenleri gösterir. Ayrıca, genellikle aşağıdaki bölümlerde açıklandığı gibi desteklenen bazı genel bağımsız değişkenler de vardır.

azure.core tabanlı kitaplıklar için bağımsız değişkenler

Bu bağımsız değişkenler Python - Yeni Kitaplıklar'da listelenen kitaplıklar için geçerlidir. Örneğin, için anahtar sözcük bağımsız değişkenlerinin bir alt kümesi aşağıda verilmiştir azure-core. Tam liste için bkz. azure-core için GitHub README.

Adı Tip Varsayılan Açıklama
logging_enable ikili False Günlüğe kaydetmeyi etkinleştirir. Daha fazla bilgi için bkz . Azure kitaplıklarında günlüğe kaydetme.
ara sunucular Dict {} Ara sunucu URL'leri. Daha fazla bilgi için bkz . Proxy'leri yapılandırma.
use_env_settings ikili True 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.
connection_timeout int 300 Azure REST API uç noktalarına bağlantı oluşturmak için saniyeler içinde zaman aşımı.
read_timeout int 300 Azure REST API işlemini tamamlama (yani yanıt bekleme) için saniyeler içinde zaman aşımı.
retry_total 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 .
retry_mode enum Üstel 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.

Tek tek kitaplıklar bu bağımsız değişkenlerin hiçbirini desteklemek zorunda değildir, bu nedenle tam ayrıntılar için her zaman her kitaplığın başvuru belgelerine bakın. Ayrıca, her kitaplık diğer bağımsız değişkenleri destekleyemeyebilir. Örneğin blob depolamaya özgü anahtar sözcük bağımsız değişkenleri için bkz. azure-storage-blob için GitHub BENİOKU.

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, yöntemiyle create_or_update bir ResourceManagementClient kaynak grubu oluşturduğunuz bir nesneniz olduğunu varsayalım. Bu yöntemin ikinci bağımsız değişkeni türündedir ResourceGroup.

yöntemini çağırmak create_or_update için, gerekli bağımsız değişkenleriylelocation (bu durumda) doğrudan ayrık bir örneği ResourceGroup 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 bağımsız değişkenleri de olabilir, bu durumda iç içe JSON da kullanabilirsiniz.

Örneğin, nesnesinin KeyVaultManagementClient bir örneğine sahip olduğunuzu ve yöntemini çağırdığınız create_or_update varsayalım. Bu durumda, üçüncü bağımsız değişken türündedir VaultCreateOrUpdateParametersve türünde bir bağımsız değişken VaultPropertiesiçerir. VaultProperties, ve türünde Skulist[AccessPolicyEntry]nesne bağımsız değişkenleri içerir. A Sku bir SkuName nesne içerir ve her AccessPolicyEntry bir nesne içerir Permissions .

Katıştırılmış nesnelerle çağırmak begin_create_or_update için aşağıdaki gibi bir kod kullanırsınız (, object_idve LOCATION zaten tanımlanmış olduğu varsayılaraktenant_id). İş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 kodunuGitHub.)

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 kullanıldığında 'sku': 'standard' bu hata oluşturulur çünkü sku parametresi satır içi JSON bekleyen bir Sku nesnedir ve bu durumda {'name': 'standard'}beklenen SkuName türle eşlenir.

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.