Pustaka klien Azure Storage Queues untuk Python - versi 12.1.4

  • Artikel

Antrean Azure Storage adalah layanan untuk menyimpan sejumlah besar pesan yang dapat diakses di mana saja melalui panggilan terautentikasi menggunakan HTTP atau HTTPS. Satu pesan antrean dapat berukuran hingga 64 KiB, dan antrean dapat berisi jutaan pesan, hingga batas kapasitas total akun penyimpanan.

Penggunaan umum penyimpanan Antrean meliputi:

  • Membuat backlog pekerjaan untuk diproses secara asinkron
  • Meneruskan pesan di antara berbagai bagian aplikasi terdistribusi

Kode sumber | Paket (PyPI) | Dokumentasi | referensi API Dokumentasi | produk Sampel

Memulai

Prasyarat

Instal paketnya

Instal pustaka klien Azure Storage Queues untuk Python dengan pip:

pip install azure-storage-queue

Buat akun penyimpanan

Jika Anda ingin membuat akun penyimpanan baru, Anda dapat menggunakan Portal Microsoft Azure, Azure PowerShell, atau Azure CLI:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Membuat klien

Pustaka klien Azure Storage Queues untuk Python memungkinkan Anda berinteraksi dengan tiga jenis sumber daya: akun penyimpanan itu sendiri, antrean, dan pesan. Interaksi dengan sumber daya ini dimulai dengan instans klien. Untuk membuat objek klien, Anda memerlukan URL titik akhir layanan antrean akun penyimpanan dan kredensial yang memungkinkan Anda mengakses akun penyimpanan:

from azure.storage.queue import QueueServiceClient

service = QueueServiceClient(account_url="https://<my-storage-account-name>.queue.core.windows.net/", credential=credential)

Mencari URL akun

Anda dapat menemukan URL layanan antrean akun penyimpanan menggunakan Portal Microsoft Azure, Azure PowerShell, atau Azure CLI:

# Get the queue service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.queue"

Jenis kredensial

Parameter credential dapat disediakan dalam sejumlah formulir yang berbeda, tergantung pada jenis otorisasi yang ingin Anda gunakan:

  1. Untuk menggunakan token tanda tangan akses bersama (SAS), berikan token sebagai string. Jika URL akun Anda menyertakan token SAS, hilangkan parameter kredensial. Anda dapat membuat token SAS dari Portal Microsoft Azure di bawah "Tanda tangan akses bersama" atau menggunakan salah generate_sas() satu fungsi untuk membuat token sas untuk akun penyimpanan atau antrean:

    from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

  2. Untuk menggunakan kunci bersama akun penyimpanan (alias kunci akun atau kunci akses), berikan kunci sebagai string. Ini dapat ditemukan di Portal Microsoft Azure di bawah bagian "Kunci Akses" atau dengan menjalankan perintah Azure CLI berikut:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Gunakan kunci sebagai parameter kredensial untuk mengautentikasi klien:

    from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")

  3. Untuk menggunakan kredensial token Azure Active Directory (AAD), berikan instans jenis kredensial yang diinginkan yang diperoleh dari pustaka identitas azure . Misalnya, DefaultAzureCredential dapat digunakan untuk mengautentikasi klien.

    Ini memerlukan beberapa penyiapan awal:

    Gunakan kredensial token yang dikembalikan untuk mengautentikasi klien:

        from azure.identity import DefaultAzureCredential
    from azure.storage.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )

Membuat klien dari string koneksi

Bergantung pada kasus penggunaan dan metode otorisasi, Anda mungkin lebih suka menginisialisasi instans klien dengan string koneksi penyimpanan alih-alih memberikan URL akun dan kredensial secara terpisah. Untuk melakukan ini, teruskan string koneksi penyimpanan ke metode kelas klien from_connection_string :

from azure.storage.queue import QueueServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = QueueServiceClient.from_connection_string(conn_str=connection_string)

String koneksi ke akun penyimpanan Anda dapat ditemukan di Portal Microsoft Azure di bawah bagian "Kunci Akses" atau dengan menjalankan perintah CLI berikut:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Konsep utama

Komponen berikut membentuk Azure Queue Service:

  • Akun penyimpanan itu sendiri
  • Antrean dalam akun penyimpanan, yang berisi sekumpulan pesan
  • Pesan dalam antrean, dalam format apa pun, hingga 64 KiB

Pustaka klien Azure Storage Queues untuk Python memungkinkan Anda berinteraksi dengan masing-masing komponen ini melalui penggunaan objek klien khusus.

Klien

Dua klien yang berbeda disediakan untuk berinteraksi dengan berbagai komponen Layanan Antrean:

  1. QueueServiceClient - klien ini mewakili interaksi dengan akun penyimpanan Azure itu sendiri, dan memungkinkan Anda memperoleh instans klien yang telah dikonfigurasi sebelumnya untuk mengakses antrean di dalamnya. Ini menyediakan operasi untuk mengambil dan mengonfigurasi properti akun serta mencantumkan, membuat, dan menghapus antrean dalam akun. Untuk melakukan operasi pada antrean tertentu, ambil klien menggunakan metode .get_queue_client
  2. QueueClient - klien ini mewakili interaksi dengan antrean tertentu (yang belum ada). Ini menyediakan operasi untuk membuat, menghapus, atau mengonfigurasi antrean dan menyertakan operasi untuk mengirim, menerima, mengintip, menghapus, dan memperbarui pesan di dalamnya.

Pesan

  • Kirim - Menambahkan pesan ke antrean dan secara opsional mengatur batas waktu visibilitas untuk pesan.
  • Terima - Mengambil pesan dari antrean dan membuatnya tidak terlihat oleh konsumen lain.
  • Intip - Mengambil pesan dari depan antrean, tanpa mengubah visibilitas pesan.
  • Pembaruan - Updates batas waktu visibilitas pesan dan/atau konten pesan.
  • Hapus - Menghapus pesan tertentu dari antrean.
  • Clear - Menghapus semua pesan dari antrean.

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Antrean Penyimpanan yang paling umum, termasuk:

Membuat antrean

Membuat antrean di akun penyimpanan Anda

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="my_queue")
queue.create_queue()

Menggunakan klien asinkron untuk membuat antrean

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="my_queue")
await queue.create_queue()

Mengirim pesan

Mengirim pesan ke antrean Anda

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="my_queue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

Mengirim pesan secara asinkron

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="my_queue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

Menerima pesan

Menerima dan memproses pesan dari antrean Anda

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="my_queue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

Menerima dan memproses pesan dalam batch

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="my_queue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

Menerima dan memproses pesan secara asinkron

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="my_queue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

Konfigurasi Opsional

Argumen kata kunci opsional yang dapat diteruskan di tingkat klien dan per operasi.

Konfigurasi Kebijakan Coba Lagi

Gunakan argumen kata kunci berikut saat membuat instans klien untuk mengonfigurasi kebijakan coba lagi:

  • retry_total (int): Jumlah total percobaan ulang yang diizinkan. Lebih diutamakan daripada hitungan lain. retry_total=0 Teruskan jika Anda tidak ingin mencoba kembali permintaan. Default ke 10.
  • retry_connect (int): Berapa banyak kesalahan terkait koneksi yang akan diulang. Default ke 3.
  • retry_read (int): Berapa kali untuk mencoba kembali kesalahan baca. Default ke 3.
  • retry_status (int): Berapa kali untuk mencoba kembali kode status yang buruk. Default ke 3.
  • retry_to_secondary (bool): Apakah permintaan harus dicoba kembali ke sekunder, jika dapat. Ini hanya boleh diaktifkan dari akun RA-GRS yang digunakan dan data yang berpotensi kedaluarsa dapat ditangani. Default ke False.

Konfigurasi klien/per operasi lainnya

Argumen kata kunci konfigurasi opsional lainnya yang dapat ditentukan pada klien atau per operasi.

Argumen kata kunci klien:

  • connection_timeout (int): Secara opsional mengatur nilai batas waktu sambungkan dan baca, dalam hitungan detik.
  • transport (Any): Transportasi yang disediakan pengguna untuk mengirim permintaan HTTP.

Argumen kata kunci per operasi:

  • raw_response_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan respons yang dikembalikan dari layanan.
  • raw_request_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan permintaan sebelum dikirim ke layanan.
  • client_request_id (str): Identifikasi permintaan yang ditentukan pengguna opsional.
  • user_agent (str): Menambahkan nilai kustom ke header agen pengguna untuk dikirim dengan permintaan.
  • logging_enable (bool): Memungkinkan pengelogan di tingkat DEBUG. Default ke False. Juga dapat diteruskan di tingkat klien untuk mengaktifkannya untuk semua permintaan.
  • header (dict): Meneruskan header kustom sebagai kunci, pasangan nilai. Misalnya headers={'CustomValue': value}

Pemecahan Masalah

Umum

Klien Antrean Penyimpanan memunculkan pengecualian yang ditentukan di Azure Core.

Daftar ini dapat digunakan untuk referensi guna menangkap pengecualian yang dilemparkan. Untuk mendapatkan kode kesalahan tertentu dari pengecualian, gunakan error_code atribut , yaitu , exception.error_code.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen :

import sys
import logging
from azure.storage.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = QueueServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

service_client.get_service_stats(logging_enable=True)

Langkah berikutnya

Lebih banyak kode sampel

Mulai menggunakan sampel Antrean kami.

Beberapa sampel Storage Queues Python SDK tersedia untuk Anda di repositori GitHub SDK. Sampel ini menyediakan kode contoh untuk skenario tambahan yang biasa ditemui saat bekerja dengan Antrean Penyimpanan:

  • queue_samples_hello_world.py (versi asinkron) - Contoh yang ditemukan dalam artikel ini:

    • Pembuatan klien
    • Buat antrean
    • Kirim pesan
    • Terima pesan

  • queue_samples_authentication.py (versi asinkron) - Contoh untuk mengautentikasi dan membuat klien:

    • Dari string koneksi
    • Dari kunci akses bersama
    • Dari token tanda tangan akses bersama
    • Dari Azure Active Directory

  • queue_samples_service.py (versi asinkron) - Contoh untuk berinteraksi dengan layanan antrean:

    • Mendapatkan dan mengatur properti layanan
    • Mencantumkan antrean di akun penyimpanan
    • Membuat dan menghapus antrean dari layanan
    • Dapatkan QueueClient

  • queue_samples_message.py (versi asinkron) - Contoh untuk bekerja dengan antrean dan pesan:

    • Menetapkan kebijakan akses
    • Mendapatkan dan mengatur metadata antrean
    • Mengirim dan menerima pesan
    • Menghapus pesan tertentu dan menghapus semua pesan
    • Mengintip dan memperbarui pesan

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang penyimpanan Azure Queue, lihat dokumentasi penyimpanan Azure Queue di docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.