Bagikan melalui

Pustaka Azure untuk pola penggunaan Python

Azure SDK untuk Python terdiri dari banyak pustaka independen, yang tercantum dalam indeks paket Python SDK.

Semua pustaka berbagi karakteristik umum dan pola penggunaan tertentu, seperti penginstalan dan penggunaan JSON sebaris untuk argumen objek.

Menyiapkan lingkungan pengembangan lokal Anda

Jika belum melakukannya, Anda dapat menyiapkan lingkungan tempat Anda dapat menjalankan kode ini. Berikut adalah beberapa opsi:

  • Konfigurasikan lingkungan virtual Python menggunakan venv atau alat pilihan Anda. Untuk mulai menggunakan lingkungan virtual, pastikan untuk mengaktifkannya. Untuk menginstal python, lihat Menginstal Python.

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

  • Gunakan lingkungan kerja conda . Untuk menginstal Conda, lihat Menginstal Miniconda.

  • Gunakan Dev Container di Visual Studio Code atau GitHub Codespaces.

Penginstalan pustaka

Pilih metode penginstalan yang sesuai dengan alat manajemen lingkungan Python Anda, baik pip atau conda.

Untuk menginstal paket pustaka tertentu, gunakan 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 mendapatkan versi terbaru dari perpustakaan di lingkungan Python Anda saat ini.

Anda juga dapat menggunakan pip untuk menghapus instalan pustaka dan menginstal versi tertentu, termasuk versi pratinjau. Untuk informasi selengkapnya, lihat Cara menginstal paket pustaka Azure untuk Python.

Operasi asinkron

Pustaka asinkron

Banyak pustaka klien dan manajemen menyediakan versi asinkron (.aio). asyncio Pustaka telah tersedia sejak Python 3.4, dan kata kunci asinkron/tunggu diperkenalkan di Python 3.5. Versi pustaka asinkron dimaksudkan untuk digunakan dengan Python 3.5 dan yang lebih baru.

Contoh pustaka Azure Python SDK dengan versi asinkron meliputi: azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio, dan azure.mgmt.compute.aio.

Perpustakaan ini memerlukan transport asinkron seperti aiohttp agar dapat berfungsi. azure-core Pustaka menyediakan transportasi asinkron, AioHttpTransport, yang digunakan oleh pustaka asinkron, sehingga Anda mungkin tidak perlu menginstal aiohttp secara terpisah.

Kode berikut menunjukkan cara membuat file python yang menunjukkan cara membuat klien untuk versi asinkron pustaka Azure Blob Storage:

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

Contoh lengkapnya ada di GitHub pada use_blob_auth_async.py. Untuk versi sinkron kode ini, lihat Contoh: Mengunggah blob.

Operasi yang memerlukan waktu lama

Beberapa operasi manajemen yang Anda panggil (seperti ComputeManagementClient.virtual_machines.begin_create_or_update dan WebAppsClient.web_apps.begin_create_or_update) mengembalikan sebuah poller untuk operasi berjangka panjang, LROPoller[<type>], di mana <type> adalah spesifik untuk operasi yang dimaksud.

Nota

Anda mungkin melihat perbedaan nama metode dalam pustaka, tergantung pada versinya dan apakah pustaka tersebut berbasis pada azure.core. Pustaka lama yang tidak didasarkan pada azure.core biasanya menggunakan nama seperti create_or_update. Pustaka yang berbasis azure.core menambahkan awalan begin_ pada nama metode untuk lebih menunjukkan bahwa mereka merupakan operasi pemantauan panjang. Memigrasikan kode lama ke pustaka berbasis azure.core yang lebih baru biasanya berarti menambahkan awalan begin_ ke nama metode, karena sebagian besar tanda tangan metode tetap sama.

Jenis LROPoller pengembalian berarti bahwa operasi tidak sinkron. Dengan demikian, Anda perlu memanggil metode poller tersebut result untuk menunggu hingga operasi selesai dan mendapatkan hasilnya.

Kode berikut, diambil dari Contoh: Membuat dan menyebarkan aplikasi web, menunjukkan contoh penggunaan poller untuk menunggu hasil:



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

Dalam hal ini, nilai pengembalian berjenis begin_create_or_updateAzureOperationPoller[Site], yang berarti bahwa nilai poller.result() yang dikembalikan adalah objek Situs.

Pengecualian

Secara umum, pustaka Azure memunculkan pengecualian saat operasi gagal dilakukan seperti yang dimaksudkan, termasuk permintaan HTTP yang gagal ke Azure REST API. Untuk kode aplikasi, Anda dapat menggunakan try...except blok di sekitar operasi pustaka.

Untuk informasi selengkapnya tentang jenis pengecualian yang mungkin dimunculkan, lihat dokumentasi untuk operasi yang dimaksud.

Penebangan kayu

Pustaka Azure terbaru menggunakan pustaka standar logging Python untuk menghasilkan output log. Anda dapat mengatur tingkat pengelogan untuk pustaka individual, grup pustaka, atau semua pustaka. Setelah mendaftarkan penangan aliran pengelogan, Anda kemudian dapat mengaktifkan pengelogan untuk objek klien tertentu atau operasi tertentu. Untuk informasi selengkapnya, lihat Pencatatan log pada pustaka Azure.

Konfigurasi proksi

Untuk menentukan proksi, Anda dapat menggunakan variabel lingkungan atau argumen opsional. Untuk informasi selengkapnya, lihat Cara mengonfigurasi proksi.

Argumen opsional untuk objek dan metode klien

Dalam dokumentasi referensi perpustakaan, Anda sering melihat argumen **kwargs atau **operation_config dalam signature konstruktor objek klien atau metode operasi tertentu. Placeholder ini menunjukkan bahwa objek atau metode yang dimaksud mungkin mendukung argumen bernama lainnya. Biasanya, dokumentasi referensi menunjukkan argumen tertentu yang dapat Anda gunakan. Ada juga beberapa argumen umum yang sering didukung seperti yang dijelaskan di bagian berikut.

Argumen untuk perpustakaan berdasarkan azure.core

Argumen ini berlaku untuk pustaka yang tercantum di Python - Pustaka Baru. Misalnya, berikut adalah subset argumen kata kunci untuk azure-core. Untuk daftar lengkapnya, lihat GitHub README untuk azure-core.

Nama Tipe Bawaan Deskripsi
aktifkan_pencatatan bool Tidak benar Mengaktifkan pengelogan. Untuk informasi selengkapnya, lihat Pencatatan log pada pustaka Azure.
Proksi kamus {} URL untuk server proksi. Untuk informasi selengkapnya, lihat Cara mengonfigurasi proksi.
gunakan_pengaturan_lingkungan bool Benar Jika True, memungkinkan penggunaan HTTP_PROXY variabel lingkungan dan HTTPS_PROXY untuk proksi. Jika False, variabel lingkungan diabaikan. Untuk informasi selengkapnya, lihat Cara mengonfigurasi proksi.
waktu_habis_koneksi int (integer) 300 Batas waktu dalam detik untuk membuat koneksi ke titik akhir Azure REST API.
batas_waktu_baca int (integer) 300 Batas waktu dalam detik untuk menyelesaikan operasi Azure REST API (yaitu, menunggu respons).
coba_ulang_total int (integer) 10 Jumlah upaya coba lagi yang diizinkan untuk panggilan REST API. Gunakan retry_total=0 untuk menonaktifkan percobaan ulang.
mode ulang coba enum eksponensial Menerapkan waktu coba lagi secara linier atau eksponensial. Jika 'tunggal', percobaan ulang dilakukan secara berkala. Jika 'eksponensial', setiap percobaan menunggu dua kali lebih lama dari percobaan sebelumnya.

Pustaka individual tidak diwajibkan untuk mendukung salah satu argumen ini, jadi selalu lihat dokumentasi referensi untuk setiap pustaka untuk detail yang tepat. Selain itu, setiap pustaka dapat mendukung argumen lain. Misalnya, untuk argumen kata kunci khusus penyimpanan blob, lihat GITHub README untuk azure-storage-blob.

Pola JSON sebaris untuk argumen objek

Banyak operasi dalam pustaka Azure memungkinkan Anda untuk mengekspresikan argumen objek baik sebagai objek diskrit atau sebagai JSON sebaris.

Misalnya, Anda memiliki objek ResourceManagementClient di mana Anda membuat grup sumber daya menggunakan metodenya create_or_update. Argumen kedua untuk metode ini berjenis ResourceGroup.

Untuk memanggil create_or_update metode , Anda dapat membuat instans diskrit secara ResourceGroup langsung dengan argumen yang diperlukan (location dalam hal ini):

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

Sebagai alternatif, Anda dapat meneruskan parameter yang sama sebagai JSON sebaris.

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

Saat Anda menggunakan JSON sebaris, pustaka Azure secara otomatis mengonversi JSON sebaris ke jenis objek yang sesuai untuk argumen yang dimaksud.

Objek juga dapat memiliki argumen objek berlapis, dalam hal ini Anda juga dapat menggunakan JSON berlapis.

Misalnya, Anda memiliki instans KeyVaultManagementClient objek, dan memanggilnya create_or_update. Dalam hal ini, argumen ketiga berjenis VaultCreateOrUpdateParameters, yang berisi argumen jenis VaultProperties. VaultProperties, pada gilirannya, berisi argumen objek jenis Sku dan list[AccessPolicyEntry]. Sebuah Sku berisi sebuah SkuName objek, dan masing-masing AccessPolicyEntry berisi sebuah Permissions objek.

Untuk memanggil begin_create_or_update dengan objek yang disematkan, Anda menggunakan kode seperti berikut (dengan asumsi tenant_id, object_id, dan LOCATION sudah ditentukan). Anda juga dapat membuat objek yang diperlukan sebelum panggilan fungsi.

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

Panggilan yang sama menggunakan JSON sebaris muncul sebagai berikut:

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

Karena kedua formulir tersebut setara, Anda dapat memilih mana pun yang Anda sukai dan bahkan mengintermiksnya. (Kode lengkap untuk contoh-contoh ini dapat ditemukan di GitHub.)

Jika JSON Anda tidak terbentuk dengan benar, Anda biasanya mendapatkan kesalahan, "DeserializationError: Tidak dapat mendeserialisasi ke objek: jenis, AttributeError: objek 'str' tidak memiliki atribut 'get'". Penyebab umum kesalahan ini adalah Anda menyediakan string tunggal untuk properti ketika pustaka mengharapkan objek JSON berlapis. Misalnya, menggunakan 'sku': 'standard' dalam contoh sebelumnya menghasilkan kesalahan ini karena parameter sku adalah objek Sku yang mengharapkan objek inline JSON, dalam hal ini {'name': 'standard'}, yang memetakan ke jenis SkuName yang diharapkan.

Langkah selanjutnya

Sekarang setelah Anda memahami pola umum untuk menggunakan pustaka Azure untuk Python, lihat contoh mandiri berikut untuk menjelajahi skenario manajemen dan pustaka klien tertentu. Anda dapat mencoba contoh ini dalam urutan apa pun karena tidak berurutan atau saling bergantung.