Bagikan melalui

Pesan, muatan, dan serialisasi

  • Artikel

Azure Bus Layanan menangani pesan. Pesan membawa muatan dan metadata. Metadata dalam bentuk pasangan kunci-nilai, dan menjelaskan payload, dan memberikan instruksi penanganan untuk Bus Layanan dan aplikasi. Kadang-kadang, metadata itu saja cukup untuk membawa informasi yang ingin disampaikan pengirim kepada penerima, dan muatan tetap kosong.

Model objek klien Service Bus resmi untuk .NET dan Java mencerminkan struktur pesan Service Bus abstrak, yang dipetakan ke dan dari protokol kawat yang didukung Service Bus.

Pesan Service Bus terdiri dari bagian muatan biner yang tidak pernah ditangani Bus Layanan dalam bentuk apa pun di sisi layanan, dan dua set properti. Properti broker sudah ditentukan sebelumnya oleh sistem. Properti yang telah ditentukan sebelumnya ini mengontrol fungsionalitas tingkat pesan di dalam broker, atau mereka memetakan ke item metadata umum dan terstandardisasi. Properti pengguna adalah kumpulan pasangan kunci-nilai yang dapat ditentukan dan diatur oleh aplikasi.

Properti broker yang sudah ditentukan sebelumnya tercantum dalam tabel berikut. Nama-nama tersebut digunakan dengan semua API klien resmi dan juga di objek JSON BrokerProperties dari pemetaan protokol HTTP.

Nama yang setara yang digunakan pada tingkat protokol AMQP tercantum dalam tanda kurung. Sementara nama-nama berikut menggunakan casing pascal, perhatikan bahwa klien JavaScript dan Python akan menggunakan casing unta dan ular masing-masing.

Nama Properti Deskripsi
ContentType (content-type) Secara opsional menjelaskan muatan pesan, dengan deskriptor mengikuti format RFC2045, Bagian 5; misalnya, application/json.
CorrelationId (correlation-id) Memungkinkan aplikasi menentukan konteks untuk pesan untuk tujuan korelasi; misalnya, mencerminkan MessageId dari pesan yang sedang dibalas.
DeadLetterSource Hanya diatur dalam pesan yang sudah diberi dead-letter dan nantinya diteruskan otomatis dari antrean dead-letter ke entitas lain. Menunjukkan entitas di mana pesan tersebut sudah diberi dead-letter. Properti ini bersifat hanya baca.
DeliveryCount

Jumlah pengiriman yang telah dicoba untuk pesan ini. Hitungannya bertahap saat kunci pesan kedaluwarsa, atau pesan secara eksplisit ditinggalkan oleh penerima. Properti ini bersifat hanya baca.

Jumlah pengiriman tidak bertahap ketika koneksi AMQP yang mendasarinya ditutup.
EnqueuedSequenceNumber Untuk pesan yang telah diteruskan otomatis, properti ini mencerminkan nomor urut yang pertama kali ditetapkan ke pesan pada titik awal pengirimannya. Properti ini bersifat hanya baca.
EnqueuedTimeUtc Instan UTC saat pesan telah diterima dan disimpan dalam entitas. Nilai ini dapat digunakan sebagai indikator waktu kedatangan yang otoritatif dan netral bila penerima tidak ingin mempercayai jam pengirim. Properti ini bersifat hanya baca.
Expires​AtUtc (absolute-expiry-time) Instan UTC saat pesan ditandai untuk dihapus dan tidak lagi tersedia untuk diambil dari entitas karena kedaluwarsanya. Kedaluwarsa dikendalikan oleh properti TimeToLive dan properti ini dihitung dari EnqueuedTimeUtc+TimeToLive. Properti ini bersifat hanya baca.
Label atau Subject (subjek) Properti ini memungkinkan aplikasi untuk menunjukkan tujuan pesan ke penerima dengan cara standar, mirip dengan baris subjek email.
Locked​Until​Utc Untuk pesan yang diambil di bawah kunci (mode terima peek-lock, tidak diawali) properti ini mencerminkan instan UTC hingga pesan dikunci dalam antrean/langganan. Ketika kunci kedaluwarsa, DeliveryCount akan bertahap dan pesan kembali tersedia untuk diambil. Properti ini bersifat hanya baca.
Lock​Token Token kunci adalah referensi ke kunci yang sedang disimpan oleh broker dalam mode terima intip-kunci. Token dapat digunakan untuk menyematkan kunci secara permanen melalui API Penangguhan dan, dengan itu, mengambil pesan dari aliran status pengiriman reguler. Properti ini bersifat hanya baca.
Message​Id (id-pesan) Pengidentifikasi pesan adalah nilai yang ditentukan aplikasi yang secara unik mengidentifikasi pesan dan muatannya. Pengidentifikasi adalah string bentuk bebas dan dapat mencerminkan GUID atau pengidentifikasi yang berasal dari konteks aplikasi. Jika diaktifkan, fitur deteksi duplikat mengidentifikasi dan menghapus pengiriman pesan kedua dan lebih lanjut dengan MessageId yang sama.
Partition​Key Untuk entitas yang dipartisi, pengaturan nilai ini memungkinkan penetapan pesan terkait ke partisi internal yang sama, sehingga urutan pengiriman dicatat dengan benar. Partisi dipilih oleh fungsi hash atas nilai ini dan tidak dapat dipilih secara langsung. Untuk entitas yang mengetahui sesi, properti SessionId akan menggantikan nilai ini.
Reply​To (balasan) Nilai opsional dan yang ditentukan aplikasi ini adalah cara standar untuk mengekspresikan jalur balasan ke penerima pesan. Ketika pengirim mengharapkan balasan, ini menetapkan nilai ke jalur absolut atau relatif dari antrean atau topik yang diharapkan balasan akan dikirim.
Reply​To​Session​Id (reply-to-group-id) Nilai ini menambah informasi ReplyTo dan menentukan SessionId mana yang harus ditetapkan untuk balasan saat dikirim ke entitas balasan.
Scheduled​Enqueue​Time​Utc Untuk pesan yang hanya tersedia untuk diambil setelah penundaan, properti ini menentukan instan UTC di mana pesan akan diantrekan secara logis, diurutkan, dan karenanya disediakan untuk diambil.
Sequence​Number Nilai urut adalah bilangan bulat 64-bit unik yang ditetapkan untuk pesan karena diterima dan disimpan oleh broker dan fungsi sebagai pengidentifikasi internalnya. Untuk entitas yang dipartisi, 16 bit teratas mencerminkan pengidentifikasi partisi. Angka urutan meningkat secara monoton dan tanpa celah. Angka urutan bergulir ke 0 ketika kisaran 48-64 bit habis. Properti ini bersifat hanya baca.
Session​Id (group-id) Untuk entitas yang mengetahui sesi, nilai yang ditentukan aplikasi ini menentukan afiliasi sesi pesan. Pesan dengan pengidentifikasi sesi yang sama tunduk pada penguncian ringkasan dan mengaktifkan pemrosesan dan demultiplexing dalam urutan yang tepat. Untuk entitas yang tidak mengetahui sesi, nilai ini diabaikan.
Time​To​Live Nilai ini adalah durasi relatif setelah pesan kedaluwarsa, mulai dari saat pesan telah diterima dan disimpan oleh broker, seperti yang ditangkap di EnqueueTimeUtc. Ketika tidak diatur secara eksplisit, nilai yang diasumsikan adalah DefaultTimeToLive untuk masing-masing antrean atau topik. Nilai TimeToLive tingkat pesan tidak boleh lebih panjang dari pengaturan DefaultTimeToLive entitas. Jika lebih lama, diam-diam disesuaikan.
To (to) Properti ini disediakan untuk digunakan di masa mendatang dalam skenario perutean dan saat ini diabaikan oleh broker itu sendiri. Aplikasi dapat menggunakan nilai ini dalam skenario rantai autoforward berbasis aturan untuk menunjukkan tujuan logis pesan yang dimaksudkan.
Via​Partition​Key Jika pesan dikirim melalui antrean transfer dalam lingkup transaksi, nilai ini memilih partisi antrean transfer.

Model pesan abstrak memungkinkan pesan diposting ke antrean melalui HTTPS dan dapat diambil melalui AMQP. Dalam kedua kasus, pesan terlihat normal dalam konteks protokol masing-masing. Properti broker diterjemahkan sesuai kebutuhan, dan properti pengguna dipetakan ke lokasi yang paling tepat pada model pesan protokol masing-masing. Di HTTP, properti pengguna memetakan langsung ke dan dari header HTTP; di AMQP yang dipetakan ke dan dari peta aplikasi-properti.

Perutean dan korelasi pesan

Subset properti broker yang dijelaskan sebelumnya, khususnya To, ReplyTo, ReplyToSessionId, MessageId, CorrelationId, dan SessionId, digunakan untuk membantu aplikasi merutekan pesan ke tujuan tertentu. Untuk mengilustrasikan fitur ini, pertimbangkan beberapa pola:

  • Permintaan/balasan sederhana: Penerbit mengirim pesan ke dalam antrean dan mengharapkan balasan dari konsumen pesan. Untuk menerima balasan, penerbit memiliki antrean tempat ia mengharapkan balasan dikirimkan. Alamat antrean dinyatakan dalam properti ReplyTo dari pesan keluar. Saat konsumen merespons, alamat antrean menyalin MessageId dari pesan yang ditangani ke properti CorrelationId dari pesan balasan dan mengirimkan pesan ke tujuan yang ditunjukkan oleh properti ReplyTo. Satu pesan dapat menghasilkan beberapa balasan, tergantung konteks aplikasi.
  • Permintaan/balasan multi-siaran: Sebagai variasi pola sebelumnya, penerbit mengirim pesan ke topik dan beberapa pelanggan menjadi layak menggunakan pesan. Masing-masing pelanggan mungkin merespons dengan cara yang dijelaskan sebelumnya. Pola ini digunakan dalam skenario penemuan atau roll-call dan responden biasanya mengidentifikasi dirinya dengan properti pengguna atau di dalam muatan. Jika ReplyTo mengarah ke topik, serangkaian respons penemuan seperti itu dapat didistribusikan ke audiens.
  • Multiplexing: Fitur sesi ini memungkinkan multiplexing streaming pesan terkait melalui satu antrean atau langganan sehingga setiap sesi (atau grup) pesan terkait, yang diidentifikasi dengan mencocokkan nilai SessionId, dirutekan ke penerima tertentu saat penerima menyimpan sesi di bawah kunci. Baca selengkapnya tentang detail sesi di sini.
  • Permintaan/balasan multipleks: Fitur sesi ini memungkinkan balasan multipleks, yang memungkinkan beberapa penerbit berbagi antrean balasan. Dengan mengatur ReplyToSessionId, penerbit dapat menginstruksikan konsumen untuk menyalin nilai tersebut ke dalam properti SessionId dari pesan balasan. Antrean atau topik penerbitan tidak perlu mengetahui sesi. Begitu pesan dikirim, penerbit kemudian dapat secara khusus menunggu sesi dengan SessionId yang ditentukan untuk sampai pada antrean dengan menerima penerima sesi secara bersyarat.

Perutean di dalam namespace Service Bus dapat diwujudkan menggunakan rantai autoforward dan aturan berlangganan topik. Perutean di seluruh namespace dapat diwujudkan menggunakan Azure LogicApps. Seperti yang ditunjukkan dalam daftar sebelumnya, properti Kepada disediakan untuk digunakan di masa mendatang dan akhirnya dapat ditafsirkan oleh broker dengan fitur yang diaktifkan khusus. Aplikasi yang ingin menerapkan perutean harus melakukannya berdasarkan properti pengguna dan tidak mengandalkan properti Kepada; akan tetapi, melakukannya sekarang tidak akan menyebabkan masalah kompatibilitas.

Serialisasi muatan

Saat transit atau disimpan di dalam Service Bus, muatan selalu berupa blok biner yang buram. Properti ContentType memungkinkan aplikasi menjelaskan muatan, dengan format yang disarankan untuk nilai properti menjadi deskripsi jenis-konten MIME sesuai IETF RFC2045; misalnya, application/json;charset=utf-8.

Tidak seperti varian Java atau .NET Standard, versi .NET Framework dari Service Bus API mendukung pembuatan instans BrokeredMessage dengan meneruskan objek .NET sesuai pilihan ke dalam konstruktor.

Pada 30 September 2026, kami akan menghentikan pustaka Azure Bus Layanan SDK WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus, dan com.microsoft.azure.servicebus, yang tidak sesuai dengan panduan Azure SDK. Kami juga akan mengakhiri dukungan protokol SBMP, sehingga Anda tidak akan lagi dapat menggunakan protokol ini setelah 30 September 2026. Migrasikan ke pustaka Azure SDK terbaru, yang menawarkan pembaruan keamanan penting dan kemampuan yang ditingkatkan, sebelum tanggal tersebut.

Meskipun pustaka lama masih dapat digunakan melebihi 30 September 2026, pustaka tersebut tidak akan lagi menerima dukungan dan pembaruan resmi dari Microsoft. Untuk informasi selengkapnya, lihat pengumuman penghentian dukungan.

Saat menggunakan legasi protokol SBMP, objek-objek tersebut kemudian diserialisasikan dengan pembuat serialisasi biner default, atau dengan pembuat serialisasi yang disediakan secara eksternal. Objek tersebut terseri dalam objek AMQP. Penerima dapat mengambil objek tersebut dengan metode GetBody <T>(), menyediakan jenis yang diharapkan. Dengan AMQP, objek diserialisasikan ke dalam grafik AMQP ArrayList dan objek IDictionary<string,object>, dan setiap klien AMQP dapat mendekodekannya.

Pada 30 September 2026, kami akan menghentikan dukungan protokol SBMP untuk Azure Bus Layanan, sehingga Anda tidak akan dapat lagi menggunakan protokol ini setelah 30 September 2026. Migrasikan ke pustaka Azure Bus Layanan SDK terbaru menggunakan protokol AMQP, yang menawarkan pembaruan keamanan penting dan kemampuan yang ditingkatkan, sebelum tanggal tersebut.

Untuk informasi selengkapnya, lihat pengumuman penghentian dukungan.

Meskipun sihir serialisasi tersembunyi ini nyaman, aplikasi harus mengambil kendali eksplisit atas serialisasi objek dan mengubah grafik objek mereka menjadi aliran sebelum memasukkannya ke dalam pesan, dan melakukan sebaliknya di sisi penerima. Ini menghasilkan hasil yang dapat dioperasikan. Meskipun AMQP memiliki model pengodean biner yang kuat, AMQP terkait dengan ekosistem olahpesan AMQP, dan klien HTTP akan kesulitan mendekode payload tersebut.

Varian .NET Standard dan Java API hanya menerima array byte, yang berarti bahwa aplikasi harus menangani kontrol serialisasi objek.

Jika payload pesan tidak dapat dideserialisasi, disarankan untuk mematikan pesan.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang olahpesan Microsoft Azure Service Bus, lihat topik berikut ini: