Mulai cepat: Pustaka klien Azure Queue Storage untuk Python

  • Artikel

Mulai menggunakan pustaka klien Azure Queue Storage untuk Python. Azure Queue Storage adalah layanan untuk menyimpan pesan dalam jumlah besar untuk nantinya diambil dan diproses. Ikuti langkah-langkah berikut untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.

Dokumentasi | referensi API Paket kode | sumber Pustaka (Indeks Paket Python)Sampel |

Gunakan pustaka klien Azure Queue Storage untuk Python untuk:

  • Membuat antrean
  • Tambahkan pesan ke antrean
  • Intip pesan dalam antrean
  • Perbarui pesan dalam antrean
  • Dapatkan panjang antrean
  • Terima pesan dari antrean
  • Hapus pesan dari antrean
  • Menghapus antrean

Prasyarat

Menyiapkan

Bagian ini memandu Anda menyiapkan proyek untuk bekerja dengan pustaka klien Azure Queue Storage untuk Python.

Membuat proyek

Buat aplikasi Python bernama queues-quickstart.

  1. Di jendela konsol (seperti cmd, PowerShell, atau Bash), buat direktori baru untuk proyek.

    mkdir queues-quickstart

  2. Beralih ke direktori queues-quickstart yang baru dibuat.

    cd queues-quickstart

Menginstal paket

Dari direktori proyek, instal pustaka klien Azure Queue Storage untuk paket Python dengan menggunakan pip install perintah . Paket identitas azure diperlukan untuk koneksi tanpa kata sandi ke layanan Azure.

pip install azure-storage-queue azure-identity

Menyiapkan kerangka kerja aplikasi

  1. Membuka file teks baru di editor kode Anda

  2. Menambahkan pernyataan import

  3. Buat struktur program, termasuk penanganan pengecualian dasar

    Berikut kodenya:

    import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.queue import QueueServiceClient, QueueClient, QueueMessage, BinaryBase64DecodePolicy, BinaryBase64EncodePolicy

try:
    print("Azure Queue storage - Python quickstart sample")
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

  4. Simpan file baru sebagai queues-quickstart.py di direktori queues-quickstart .

Mengautentikasi Azure

Permintaan aplikasi ke sebagian besar layanan Azure harus diotorisasi. Menggunakan kelas yang DefaultAzureCredential disediakan oleh pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda.

Anda juga dapat mengotorisasi permintaan ke layanan Azure menggunakan kata sandi, string koneksi, atau kredensial lainnya secara langsung. Namun, pendekatan ini harus digunakan dengan hati-hati. Pengembang harus rajin untuk tidak pernah mengekspos rahasia ini di lokasi yang tidak aman. Siapa pun yang mendapatkan akses ke kata sandi atau kunci rahasia dapat mengautentikasi. DefaultAzureCredential menawarkan keuntungan pengelolaan dan keamanan yang ditingkatkan melalui kunci akun untuk memungkinkan autentikasi tanpa kata sandi. Kedua opsi diperlihatkan dalam contoh berikut.

DefaultAzureCredential adalah kelas yang disediakan oleh pustaka klien Azure Identity untuk Python. Untuk mempelajari selengkapnya tentang DefaultAzureCredential, lihat gambaran umum DefaultAzureCredential. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode autentikasi yang harus digunakan saat runtime bahasa umum. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per lingkungan.

Misalnya, aplikasi Anda dapat mengautentikasi menggunakan kredensial masuk Visual Studio Code Saat mengembangkan secara lokal, lalu menggunakan identitas terkelola setelah disebarkan ke Azure. Tidak diperlukan perubahan kode untuk transisi ini.

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data antrean memiliki izin yang benar. Anda memerlukan Kontributor Data Antrean Penyimpanan untuk membaca dan menulis data antrean. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.

Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut akan menetapkan peran Kontributor Data Antrean Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data antrean di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

A screenshot showing how to assign a role.

  1. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Antrean Penyimpanan dan pilih hasil yang cocok lalu pilih Berikutnya.

  2. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  3. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  4. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Model objek

Azure Queue Storage adalah layanan untuk menyimpan pesan dalam jumlah besar. Pesan antrean dapat berukuran hingga 64 KB. Antrean dapat berisi jutaan pesan, hingga mencapai batas kapasitas total dari akun penyimpanan. Antrean umumnya digunakan untuk membuat backlog pekerjaan untuk diproses secara asinkron. Queue Storage menawarkan tiga jenis sumber daya:

  • Akun penyimpanan: Semua akses ke Azure Storage dilakukan melalui akun penyimpanan. Untuk informasi selengkapnya tentang akun penyimpanan, lihat Gambaran umum akun penyimpanan
  • Antrean: Antrean berisi sekumpulan pesan. Semua pesan harus dalam antrean. Perhatikan bahwa nama antrean harus ditulis dengan huruf kecil semua. Untuk mendapatkan informasi tentang penamaan antrean, lihat Penamaan Antrean dan Metadata.
  • Pesan: Pesan, dalam format apa pun, dapat mencapai ukuran 64 KB. Pesan dapat tetap dalam antrean selama maksimal 7 hari. Untuk versi 29-07-2017 atau yang lebih baru, waktu untuk aktif maksimum dapat berupa angka positif apa pun, atau -1 yang menunjukkan bahwa pesan belum kedaluwarsa. Jika parameter ini dihilangkan, time-to-live default adalah tujuh hari.

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram of Queue storage architecture

Gunakan kelas Python berikut untuk berinteraksi dengan sumber daya ini:

  • QueueServiceClient: QueueServiceClient memungkinkan Anda mengelola semua antrean di akun penyimpanan Anda.
  • QueueClient: Kelas QueueClient memungkinkan Anda mengelola dan memanipulasi antrean individual dan pesannya.
  • QueueMessage: Kelas QueueMessage mewakili objek individual yang dikembalikan saat memanggil receive_messages dalam antrean.

Contoh kode

Contoh cuplikan kode ini menunjukkan cara melakukan tindakan berikut dengan pustaka klien Azure Queue Storage untuk Python:

Mengotorisasi akses dan membuat objek klien

Pastikan Anda diautentikasi dengan akun Microsoft Entra yang sama dengan yang Anda tetapkan perannya. Anda dapat mengautentikasi melalui Azure CLI, Visual Studio Code, atau Azure PowerShell.

Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:

az login

Setelah diautentikasi, Anda dapat membuat dan mengotorisasi QueueClient objek menggunakan DefaultAzureCredential untuk mengakses data antrean di akun penyimpanan. DefaultAzureCredential secara otomatis menemukan dan menggunakan akun yang Anda gunakan untuk masuk di langkah sebelumnya.

Untuk mengotorisasi menggunakan DefaultAzureCredential, pastikan Anda telah menambahkan paket identitas azure , seperti yang dijelaskan dalam Menginstal paket. Selain itu, pastikan untuk menambahkan pernyataan impor berikut dalam file queues-quickstart.py :

from azure.identity import DefaultAzureCredential

Tentukan nama untuk antrean dan buat instans QueueClient kelas, menggunakan DefaultAzureCredential untuk otorisasi. Kami menggunakan objek klien ini untuk membuat dan berinteraksi dengan sumber daya antrean di akun penyimpanan.

Penting

Nama antrean hanya boleh berisi huruf kecil, angka, dan tanda hubung, dan harus dimulai dengan huruf atau angka. Setiap tanda hubung harus diawali dan diikuti dengan karakter non-tanda hubung. Panjang nama harus antara 3 hingga 63 karakter. Untuk informasi tentang penamaan antrean, lihat Penamaan antrean dan metadata.

Tambahkan kode berikut di dalam try blok, dan pastikan untuk mengganti <storage-account-name> nilai tempat penampung:

    print("Azure Queue storage - Python quickstart sample")

    # Create a unique name for the queue
    queue_name = "quickstartqueues-" + str(uuid.uuid4())

    account_url = "https://<storageaccountname>.queue.core.windows.net"
    default_credential = DefaultAzureCredential()

    # Create the QueueClient object
    # We'll use this object to create and interact with the queue
    queue_client = QueueClient(account_url, queue_name=queue_name ,credential=default_credential)

Pesan antrean disimpan sebagai teks. Jika Anda ingin menyimpan data biner, siapkan fungsi pengodean dan dekode Base64 sebelum memasukkan pesan ke dalam antrean.

Anda dapat mengonfigurasi fungsi pengodean dan decoding Base64 saat membuat objek klien:

# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
                            conn_str=connect_str, queue_name=q_name,
                            message_encode_policy = BinaryBase64EncodePolicy(),
                            message_decode_policy = BinaryBase64DecodePolicy()
                        )

Membuat antrean

QueueClient Dengan menggunakan objek , panggil create_queue metode untuk membuat antrean di akun penyimpanan Anda.

Tambahkan kode ini ke akhir blok try:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Tambahkan pesan ke antrean

Cuplikan kode berikut menambahkan pesan ke antrean dengan memanggil metode send_message. Kode ini juga menyimpan QueueMessage yang dikembalikan dari panggilan send_message ketiga. saved_message digunakan untuk nantinya memperbarui isi pesan dalam program.

Tambahkan kode ini ke akhir blok try:

    print("\nAdding messages to the queue...")

    # Send several messages to the queue
    queue_client.send_message(u"First message")
    queue_client.send_message(u"Second message")
    saved_message = queue_client.send_message(u"Third message")

Intip pesan dalam antrean

Lihat sekilas pesan dalam antrean dengan memanggil metode peek_messages. Metode ini mengambil satu atau beberapa pesan dari depan antrean tanpa mengubah visibilitas pesan.

Tambahkan kode ini ke akhir blok try:

    print("\nPeek at the messages in the queue...")

    # Peek at messages in the queue
    peeked_messages = queue_client.peek_messages(max_messages=5)

    for peeked_message in peeked_messages:
        # Display the message
        print("Message: " + peeked_message.content)

Perbarui pesan dalam antrean

Perbarui konten pesan dengan memanggil metode update_message. Metode ini dapat mengubah visibilitas batas waktu dan isi pesan. Isi pesan harus merupakan string berkode UTF-8 yang berukuran hingga 64 KB. Bersama dengan isi baru, berikan nilai dari pesan yang disimpan sebelumnya dalam kode. Nilai saved_message mengenali pesan mana yang akan diperbarui.

    print("\nUpdating the third message in the queue...")

    # Update a message using the message saved when calling send_message earlier
    queue_client.update_message(saved_message, pop_receipt=saved_message.pop_receipt, \
        content="Third message has been updated")

Dapatkan panjang antrean

Anda bisa mendapat estimasi jumlah pesan dalam antrean.

Metode get_queue_properties mengembalikan properti antrean termasuk approximate_message_count.

properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))

Hasilnya adalah perkiraan karena pesan dapat ditambahkan atau dihapus setelah layanan merespons permintaan Anda.

Terima pesan dari antrean

Anda dapat mengunduh pesan yang ditambahkan sebelumnya dengan memanggil receive_messages metode .

Tambahkan kode ini ke akhir blok try:

    print("\nReceiving messages from the queue...")

    # Get messages from the queue
    messages = queue_client.receive_messages(max_messages=5)

Saat memanggil receive_messages metode , Anda dapat secara opsional menentukan nilai untuk max_messages, yang merupakan jumlah pesan yang akan diambil dari antrean. Defaultnya adalah 1 pesan dan maksimum adalah 32 pesan. Anda juga dapat menentukan nilai untuk visibility_timeout, yang menyembunyikan pesan dari operasi lain untuk periode batas waktu. Defaultnya adalah 30 detik.

Hapus pesan dari antrean

Hapus pesan dari antrean setelah diterima dan diproses. Dalam kasus ini, pemrosesan hanya menampilkan pesan di konsol.

Aplikasi berhenti sejenak untuk input pengguna dengan memanggil input sebelum memproses dan menghapus pesan. Pastikan di portal Microsoft Azure Anda bahwa sumber daya dibuat dengan benar, sebelum dihapus. Setiap pesan yang tidak dihapus secara eksplisit akhirnya menjadi terlihat dalam antrean lagi untuk kesempatan lain untuk memprosesnya.

Tambahkan kode ini ke akhir blok try:

    print("\nPress Enter key to 'process' messages and delete them from the queue...")
    input()

    for msg_batch in messages.by_page():
            for msg in msg_batch:
                # "Process" the message
                print(msg.content)
                # Let the service know we're finished with
                # the message and it can be safely deleted.
                queue_client.delete_message(msg)

Menghapus antrean

Kode berikut membersihkan sumber daya yang dibuat aplikasi dengan menghapus antrean menggunakan metode delete_queue.

Tambahkan kode ini ke akhir blok try dan simpan file:

    print("\nPress Enter key to delete the queue...")
    input()

    # Clean up
    print("Deleting queue...")
    queue_client.delete_queue()

    print("Done")

Menjalankan kode

Aplikasi ini membuat dan menambahkan tiga pesan ke antrean Azure. Kode mencantumkan pesan dalam antrean, lalu mengambil dan menghapusnya, sebelum akhirnya menghapus antrean.

Di jendela konsol Anda, navigasikan ke direktori yang berisi file queues-quickstart.py , lalu gunakan perintah berikut python untuk menjalankan aplikasi.

python queues-quickstart.py

Output aplikasi mirip dengan contoh berikut:

Azure Queue Storage client library - Python quickstart sample
Creating queue: quickstartqueues-<UUID>

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

First message
Second message
Third message has been updated

Press Enter key to delete the queue...

Deleting queue...
Done

Saat aplikasi berhenti sejenak sebelum menerima pesan, periksa akun penyimpanan Anda di portal Microsoft Azure. Pastikan pesan berada dalam antrean.

Tekan tombol Enter untuk menerima dan menghapus pesan. Ketika diminta, tekan tombol Enter lagi untuk menghapus antrean dan menyelesaikan demo.

Langkah berikutnya

Dalam mulai cepat ini, Anda belajar cara membuat antrean dan menambahkan pesan ke dalamnya menggunakan kode Python. Kemudian Anda belajar mengintip, mengambil, dan menghapus pesan. Terakhir, Anda belajar cara menghapus antrean pesan.

Untuk tutorial, sampel, mulai cepat, dan dokumentasi lainnya, kunjungi:

Pengembang Azure untuk Python