Pustaka klien Azure Web PubSub untuk Python

Nota

Detail tentang istilah yang digunakan di sini dijelaskan dalam artikel konsep utama.

SDK sisi klien bertujuan untuk mempercepat alur kerja pengembang; lebih spesifik,

• menyederhanakan pengelolaan koneksi klien
• menyederhanakan pengiriman pesan di antara klien
• secara otomatis mencoba kembali setelah penurunan koneksi klien yang tidak diinginkan
• dengan andal mengirimkan pesan dalam jumlah dan secara berurutan setelah pulih dari penurunan koneksi

Seperti yang ditunjukkan dalam diagram, klien Anda membuat koneksi WebSocket dengan sumber daya Web PubSub Anda.

Memulai Langkah Awal

Prasyarat

• Python 3.8+
• Langganan Azure
• Sumber daya Web PubSub

1. Instal paket azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Sambungkan dengan sumber daya Web PubSub Anda

Klien menggunakan Client Access URL untuk menyambungkan dan mengautentikasi dengan layanan, yang mengikuti pola wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Klien dapat memiliki beberapa cara untuk mendapatkan Client Access URL. Untuk mulai cepat ini, Anda dapat menyalin dan menempelkannya dari portal Microsoft Azure yang ditampilkan.

Seperti yang ditunjukkan dalam diagram, klien memiliki izin untuk mengirim pesan ke dan bergabung dengan grup tertentu bernama group1.

from azure.messaging.webpubsubclient import WebPubSubClient

client = WebPubSubClient("<client-access-url>")
with client:
    # The client can join/leave groups, send/receive messages to and from those groups all in real-time
    ...

3. Bergabung dengan grup

Klien hanya dapat menerima pesan dari grup yang telah bergabung dan Anda perlu menambahkan panggilan balik untuk menentukan logika saat menerima pesan.

from azure.messaging.webpubsubclient.models import CallbackType

# ...continues the code snippet from above

# Registers a listener for the event 'group-message' early before joining a group to not miss messages
group_name = "group1";
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message: {e.data}"));

# A client needs to join the group it wishes to receive messages from
client.join_group(groupName);

4. Mengirim pesan ke grup

# ...continues the code snippet from above

# Send a message to a joined group
client.send_to_group(group_name, "hello world", "text");

# In the Console tab of your developer tools found in your browser, you should see the message printed there.

Contoh

Menambahkan panggilan balik untuk connected, disconnected dan stopped peristiwa

1. Ketika klien berhasil terhubung ke sumber daya Web PubSub Anda, peristiwa connected dipicu.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Connection {e.connection_id} is connected"))
   

2. Ketika klien terputus dan gagal memulihkan koneksi, peristiwa disconnected dipicu.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.DISCONNECTED, lambda e: print(f"Connection disconnected: {e.message}"))
   

3. Peristiwa stopped dipicu ketika klien terputus dan klien berhenti mencoba menyambungkan kembali. Ini biasanya terjadi setelah client.stop() dipanggil, atau auto_reconnect dinonaktifkan atau batas yang ditentukan untuk mencoba menyambungkan kembali telah tercapai. Jika Anda ingin memulai ulang klien, Anda dapat memanggil client.start() dalam peristiwa yang dihentikan.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.STOPPED, lambda : print("Client has stopped"))
   

Klien menggunakan pesan dari server aplikasi atau grup yang bergabung

Klien dapat menambahkan panggilan balik untuk menggunakan pesan dari server atau grup aplikasi Anda. Catatan, jika group-message klien hanya dapat menerima pesan grup yang telah bergabung.

from azure.messaging.webpubsubclient.models import CallbackType

# Registers a listener for the "server-message". The callback is invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Received message {e.data}"))

# Registers a listener for the "group-message". The callback is invoked when the client receives a message from the groups it has joined.
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message from {e.group}: {e.data}"))

---

Menangani kegagalan bergabung kembali

Ketika klien terputus dan gagal pulih, semua konteks grup dibersihkan di sumber daya Web PubSub Anda. Ini berarti ketika klien terhubung kembali, klien perlu bergabung kembali dengan grup. Secara default, klien memiliki opsi auto_rejoin_groups diaktifkan.

Namun, Anda harus menyadari batasan auto_rejoin_groups.

• Klien hanya dapat bergabung kembali dengan grup yang awalnya digabungkan dengan kode klien bukan oleh kode sisi server.
• Operasi "bergabung kembali dengan grup" mungkin gagal karena berbagai alasan, misalnya, klien tidak memiliki izin untuk bergabung dengan grup. Dalam kasus seperti itu, Anda perlu menambahkan panggilan balik untuk menangani kegagalan ini.

from azure.messaging.webpubsubclient.models import CallbackType

# By default auto_rejoin_groups=True. You can disable it by setting to False.
client = WebPubSubClient("<client-access-url>", auto_rejoin_groups=True);

# Registers a listener to handle "rejoin-group-failed" event
client.subscribe(CallbackType.REJOIN_GROUP_FAILED, lambda e: print(f"Rejoin group {e.group} failed: {e.error}"))

Operasi dan coba lagi

Secara default, operasi seperti client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() memiliki tiga percobaan ulang. Anda dapat mengonfigurasi melalui argumen key-word. Jika semua percobaan ulang gagal, kesalahan akan muncul. Anda dapat terus mencoba kembali dengan meneruskan ack_id yang sama dengan percobaan ulang sebelumnya sehingga layanan Web PubSub dapat mendeduplikasi operasi.

try:
    client.join_group(group_name)
except SendMessageError as e:
    client.join_group(group_name, ack_id=e.ack_id)

Pemecahan masalah

Aktifkan log

Anda dapat mengatur variabel lingkungan berikut untuk mendapatkan log debug saat menggunakan pustaka ini.

export AZURE_LOG_LEVEL=verbose

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

Pelacakan Langsung

Gunakan alat Live Trace dari portal Azure untuk memeriksa lalu lintas pesan langsung melalui sumber daya Web PubSub Anda.