Pola penggunaan pustaka Azure untuk Python

Artikel
10/18/2023

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 ini adalah beberapa opsi:

Mengonfigurasi lingkungan virtual Python. Anda dapat membuat lingkungan virtual secara lokal atau di Azure Cloud Shell dan menjalankan kode di sana. Pastikan untuk mengaktifkan lingkungan virtual untuk mulai menggunakannya.
Gunakan lingkungan conda.
Gunakan Kontainer Dev di Visual Studio Code atau GitHub Codespaces.

Untuk menginstal paket pustaka tertentu, gunakan 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 mengambil pustaka versi terbaru 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.

Untuk menginstal paket pustaka tertentu di lingkungan Conda, gunakan 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 mengambil paket versi terbaru di lingkungan Conda Anda saat ini.

Untuk informasi selengkapnya, termasuk cara menghapus paket atau menginstal versi tertentu, 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 asinkron pustaka 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.

Pustaka ini memerlukan transportasi asinkron seperti aiohttp untuk bekerja. azure-core Pustaka menyediakan transportasi asinkron, AioHttpTransport, yang digunakan oleh pustaka asinkron.

Kode berikut 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 jangka panjang

Beberapa operasi manajemen yang Anda panggil (seperti ComputeManagementClient.virtual_machines.begin_create_or_update dan WebSiteManagementClient.web_apps.begin_create_or_update mengembalikan poller untuk operasi jangka panjang, LROPoller[<type>], di mana <type> khusus untuk operasi yang dimaksud.

Catatan

Anda mungkin melihat perbedaan nama metode di pustaka, yang disebabkan oleh perbedaan versi. Pustaka lama yang tidak didasarkan pada azure.core biasanya menggunakan nama seperti create_or_update. Pustaka berdasarkan azure.core menambahkan begin_ awalan ke nama metode untuk lebih menunjukkan bahwa pustaka tersebut adalah operasi polling 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 harus memanggil metode result poller untuk menunggu operasi selesai dan mendapatkan hasilnya.

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

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 meningkatkan pengecualian ketika operasi gagal berfungsi sebagaimana dimaksud, termasuk permintaan HTTP yang gagal ke REST API Azure. Untuk kode aplikasi, Anda dapat menggunakan try...except blok di sekitar operasi pustaka.

Untuk informasi lebih lanjut tentang jenis pengecualian yang mungkin diajukan, lihat dokumentasi untuk operasi terkait.

Pencatatan

Pustaka Azure terbaru menggunakan pustaka logging standar Python untuk menghasilkan output log. Anda dapat mengatur tingkat pengelogan untuk pustaka individual, grup pustaka, atau semua pustaka. Setelah Anda mendaftarkan pengatur aliran pengelogan, Anda kemudian dapat mengaktifkan pengelogan untuk objek klien tertentu atau operasi tertentu. Untuk informasi selengkapnya, lihat Pengelogan di 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 pustaka, Anda sering melihat argumen **kwargs atau **operation_config dalam tanda tangan konstruktor objek klien atau metode operasi tertentu. Tempat penampung ini menunjukkan bahwa objek atau metode yang dimaksud dapat mendukung argumen bernama lainnya. Biasanya, dokumentasi referensi menunjukkan argumen spesifik yang dapat Anda gunakan. Terdapat juga beberapa argumen umum yang sering didukung seperti yang dijelaskan di bagian berikut.

Argumen untuk pustaka 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	Default	Deskripsi
logging_enable	bool	Salah	Memungkinkan pengelogan. Untuk informasi selengkapnya, lihat Pengelogan di pustaka Azure.
proksi	kamus	{}	URL server proksi. Untuk informasi selengkapnya, lihat Cara mengonfigurasi proksi.
use_env_settings	bool	Benar	Jika True, memungkinkan penggunaan variabel lingkungan `HTTP_PROXY` dan `HTTPS_PROXY` untuk proksi. Jika False, variabel lingkungan diabaikan. Untuk informasi selengkapnya, lihat Cara mengonfigurasi proksi.
connection_timeout	int	300	Batas waktu dalam hitungan detik untuk membuat koneksi ke titik akhir REST API Azure.
read_timeout	int	300	Batas waktu dalam hitungan detik untuk menyelesaikan operasi REST API Azure (yaitu, menunggu respons).
retry_total	int	10	Jumlah upaya percobaan kembali yang diizinkan untuk panggilan REST API. Gunakan `retry_total=0` untuk menonaktifkan percobaan kembali.
retry_mode	enum	eksponensial	Menerapkan waktu percobaan kembali secara linier atau eksponensial. Jika 'tunggal', percobaan kembali dilakukan secara berkala. Jika 'eksponensial', setiap percobaan kembali menunggu dua kali lebih lama dari percobaan kembali 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 ResourceManagementClient objek tempat Anda membuat grup sumber daya dengan metodenya create_or_update . Argumen kedua untuk metode ini adalah jenis 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 dengan 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, jika Anda memiliki instans objek KeyVaultManagementClient, dan memanggil metode create_or_update. Dalam hal ini, argumen ketiga adalah jenis VaultCreateOrUpdateParameters, yang dengan sendirinya berisi argumen jenis VaultProperties. VaultProperties, pada gilirannya, berisi argumen objek jenis Sku dan list[AccessPolicyEntry]. Sku berisi objek SkuName, dan masing-masing AccessPolicyEntry berisi objek Permissions.

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 ditampilkan 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 bentuk tersebut setara, Anda dapat memilih mana yang Anda inginkan dan bahkan mencampurnya. (Kode lengkap untuk contoh-contoh ini dapat ditemukan di GitHub.)

Jika JSON Anda tidak terbentuk dengan benar, Anda biasanya mendapatkan kesalahan, "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'". Penyebab umum dari kesalahan ini adalah Anda menyediakan satu string untuk properti saat pustaka mengharapkan objek JSON berlapis. Misalnya, menggunakan 'sku': 'standard' dalam contoh sebelumnya menghasilkan kesalahan ini karena parameter sku adalah objek Sku yang mengharapkan JSON objek sebaris, dalam hal ini {'name': 'standard'}, yang memetakan ke jenis SkuName yang diharapkan.

Langkah berikutnya

Sekarang setelah Anda memahami pola umum dalam 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.