Referensi API MQTT 5 sarana data IoT Hub (pratinjau)

Dokumen ini mendefinisikan operasi yang tersedia dalam versi 2.0 (versi api: 2020-10-01-preview) dari API sarana data IoT Hub.

Catatan

IoT Hub memiliki dukungan fitur terbatas untuk MQTT. Jika solusi Anda memerlukan dukungan MQTT v3.1.1 atau v5, kami sarankan dukungan MQTT di Azure Event Grid. Untuk informasi selengkapnya, lihat Membandingkan dukungan MQTT di IoT Hub dan Event Grid.

Operasional

Mendapatkan kembaran

Mendapatkan status kembaran

Permintaan

Nama topik:$iothub/twin/get

Properti: tidak ada

Payload: kosong

Respons Keberhasilan

Properti: tidak ada

Payload: Kembar

Respons Alternatif

Keadaan	Nama	Deskripsi
0100	Permintaan Buruk	Pesan operasi salah format dan tidak dapat diproses.
0101	Tidak Diizinkan	Klien tidak berwenang untuk melakukan operasi.
0102	Tidak Diperbolehkan	Operasi tidak diperbolehkan.
0501	Dibatasi	tingkat permintaan terlalu tinggi per SKU
0502	Kuota Terlampaui	kuota harian per SKU saat ini terlampaui
0601	Kesalahan Server	kesalahan server internal
0602	Waktu habis	waktu operasi habis sebelum operasi selesai
0603	Server Sibuk	server sibuk

Sampel kode semu

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Patch Kembar Dilaporkan

Status patch Kembar yang dilaporkan

Permintaan

Nama topik:$iothub/twin/patch/reported

Properti:

Nama	Tipe	Wajib	Deskripsi
if-version	u64	no

Payload: TwinState

Respons Keberhasilan

Properti:

Nama	Tipe	Wajib	Deskripsi
versi	u64	yes	Versi status yang dilaporkan setelah patch diterapkan

Payload: kosong

Respons Alternatif

Keadaan	Nama	Deskripsi
0104	Prasyarat gagal	prasyarat tidak terpenuhi yang mengakibatkan permintaan dibatalkan
0100	Permintaan Buruk	Pesan operasi salah format dan tidak dapat diproses.
0101	Tidak Diizinkan	Klien tidak berwenang untuk melakukan operasi.
0102	Tidak Diperbolehkan	Operasi tidak diperbolehkan.
0501	Dibatasi	tingkat permintaan terlalu tinggi per SKU
0502	Kuota Terlampaui	kuota harian per SKU saat ini terlampaui
0601	Kesalahan Server	kesalahan server internal
0602	Waktu habis	waktu operasi habis sebelum operasi selesai
0603	Server Sibuk	server sibuk

Sampel kode semu

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/reported
    [if-version: <u64>]
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Terima Perintah

Terima dan tangani perintah

Pesan

Nama topik:$iothub/commands

Properti:

Nama	Tipe	Wajib	Deskripsi
sequence-no	u64	yes	Mengurutkan nomor pesan
enqueued-time	waktu	yes	Tanda waktu ketika pesan memasuki sistem
delivery-count	u32	yes	Jumlah percobaan pengiriman pesan telah dilakukan
creation-time	waktu	no	Tanda waktu saat pesan dibuat (disediakan oleh pengirim)
message-id	string	no	Identitas pesan (disediakan oleh pengirim)
user_id	string	no	Identitas pengguna (disediakan oleh pengirim)
correlation-id	string	no	Identitas korelasi (disediakan oleh pengirim)
Jenis Konten	string	no	menentukan Jenis Konten payload
content-encoding	string	no	menentukan Pengodean Konten payload

Payload: urutan byte apapun

Konfirmasi Keberhasilan

Menunjukkan bahwa perintah telah diterima untuk ditangani oleh klien

Properti: tidak ada

Payload: kosong

Konfirmasi Alternatif

Kode Alasan	Keadaan	Nama	Deskripsi
131	0603	Tinggalkan	Menunjukkan perintah tidak akan diproses saat ini dan harus disebarkan ulang di masa mendatang.
131	0100	Tolak	Menunjukkan klien menolak perintah dan tidak boleh dicoba lagi.

Sampel kode semu

-> SUBSCRIBE
    - Topic: $iothub/commands
      QoS: 1
<- PUBLISH
    QoS: 1
    Topic: $iothub/commands
    sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
    Payload: ...

-> PUBACK

Terima Metode Langsung

Menerima dan menangani panggilan Metode Langsung

Permintaan

Nama topik:$iothub/methods/{name}

Properti: tidak ada

Payload: urutan byte apapun

Respons Keberhasilan

Properti:

Nama	Tipe	Wajib	Deskripsi
response-code	u32	yes

Payload: urutan byte apapun

Respons Alternatif

Keadaan	Nama	Deskripsi
06A0	Tidak tersedia	Menunjukkan bahwa klien tidak dapat dijangkau melalui koneksi ini.

Sampel kode semu

-> SUBSCRIBE
    - Topic: methods/{name}
      QoS: 0
<- SUBACK
<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/{name}
-> PUBLISH
    QoS: 0
    Topic: $iothub/responses

Terima Perubahan Status yang Diinginkan Kembar

Menerima pembaruan untuk status yang diinginkan Kembar

Pesan

Nama topik:$iothub/twin/patch/desired

Properti:

Nama	Tipe	Wajib	Deskripsi
versi	u64	yes	Versi status yang diinginkan cocok dengan pembaruan ini

Payload: TwinState

Sampel kode semu

-> SUBSCRIBE
    - Topic: $iothub/twin/patch/desired
      QoS: 0
<- PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/desired
    version: <u64>
    Payload: ...

Kirim Telemetri

Posting pesan ke saluran telemetri - Azure Event Hubs secara default atau titik akhir lainnya melalui konfigurasi perutean.

Pesan

Nama topik:$iothub/telemetry

Properti:

Nama	Tipe	Wajib	Deskripsi
Jenis Konten	string	no	menerjemahkan ke dalam properti sistem content-type pada pesan yang diposting
content-encoding	string	no	menerjemahkan ke dalam properti sistem content-encoding pada pesan yang diposting
message-id	string	no	menerjemahkan ke dalam properti sistem message-id pada pesan yang diposting
user_id	string	no	menerjemahkan ke dalam properti sistem user-id pada pesan yang diposting
correlation-id	string	no	menerjemahkan ke dalam properti sistem correlation-id pada pesan yang diposting
creation-time	waktu	no	menerjemahkan ke dalam properti iothub-creation-time-utc pada pesan yang diposting

Tip

Format creation-time harus UTC tanpa informasi zona waktu. Misalnya, 2021-04-21T11:30:16Z valid, 2021-04-21T11:30:16-07:00 tidak valid.

Payload: urutan byte apapun

Konfirmasi Keberhasilan

Pesan telah berhasil diposting ke saluran telemetri

Properti: tidak ada

Payload: kosong

Konfirmasi Alternatif

Kode Alasan	Keadaan	Nama	Deskripsi
131	0100	Permintaan Buruk	Pesan operasi salah format dan tidak dapat diproses.
135	0101	Tidak Diizinkan	Klien tidak berwenang untuk melakukan operasi.
131	0102	Tidak Diperbolehkan	Operasi tidak diperbolehkan.
131	0601	Kesalahan Server	kesalahan server internal
151	0501	Dibatasi	tingkat permintaan terlalu tinggi per SKU
151	0502	Kuota Terlampaui	kuota harian per SKU saat ini terlampaui
131	0602	Waktu habis	waktu operasi habis sebelum operasi selesai
131	0603	Server Sibuk	server sibuk

Sampel kode semu

-> PUBLISH
    QoS: 1
    Topic: $iothub/telemetry
    [Content Type: <string>]
    [content-encoding: <string>]
    [message-id: <string>]
    [user-id: <string>]
    [correlation-id: <string>]
    [creation-time: <time>]

<- PUBACK

Respons

Permintaan Buruk

Pesan operasi salah format dan tidak dapat diproses.

Kode Alasan:131

Status0100:

Properti:

Nama	Tipe	Wajib	Deskripsi
reason	string	no	berisi informasi tentang apa yang secara khusus tidak valid tentang pesan

Payload: kosong

Konflik

Operasi bertentangan dengan operasi lain yang sedang berlangsung.

Kode Alasan:131

Status0103:

Properti:

Nama	Tipe	Wajib	Deskripsi
trace-id	string	no	ID pelacakan untuk korelasi dengan diagnostik lain untuk kesalahan
reason	string	no	berisi informasi tentang apa yang secara khusus tidak valid tentang pesan

Payload: kosong

Tidak Diperbolehkan

Operasi tidak diperbolehkan.

Kode Alasan:131

Status0102:

Properti:

Nama	Tipe	Wajib	Deskripsi
reason	string	no	berisi informasi tentang apa yang secara khusus tidak valid tentang pesan

Payload: kosong

Tidak Diizinkan

Klien tidak berwenang untuk melakukan operasi.

Kode Alasan:135

Status0101:

Properti:

Nama	Tipe	Wajib	Deskripsi
trace-id	string	no	ID pelacakan untuk korelasi dengan diagnostik lain untuk kesalahan

Payload: kosong

Tidak Ditemukan

sumber daya yang diminta tidak ada

Kode Alasan:131

Status0504:

Properti:

Nama	Tipe	Wajib	Deskripsi
reason	string	no	berisi informasi tentang apa yang secara khusus tidak valid tentang pesan

Payload: kosong

Tidak Diubah

Sumber daya tidak dimodifikasi berdasarkan prasyarat yang disediakan.

Kode Alasan:0

Status0001:

Properti: tidak ada

Payload: kosong

Prasyarat gagal

Prasyarat tidak terpenuhi mengakibatkan permintaan dibatalkan

Kode Alasan:131

Status0104:

Properti: tidak ada

Payload: kosong

Kuota Terlampaui

kuota harian per SKU saat ini terlampaui

Kode Alasan:151

Status0502:

Properti: tidak ada

Payload: kosong

Sumber Daya Telah Habis

sumber daya kehabisan kapasitas untuk menyelesaikan operasi

Kode Alasan:131

Status0503:

Properti:

Nama	Tipe	Wajib	Deskripsi
reason	string	no	berisi informasi tentang apa yang secara khusus tidak valid tentang pesan

Payload: kosong

Server Sibuk

server sibuk

Kode Alasan:131

Status0603:

Properti:

Nama	Tipe	Wajib	Deskripsi
trace-id	string	no	ID pelacakan untuk korelasi dengan diagnostik lain untuk kesalahan

Payload: kosong

Kesalahan Server

kesalahan server internal

Kode Alasan:131

Status0601:

Properti:

Nama	Tipe	Wajib	Deskripsi
trace-id	string	no	ID pelacakan untuk korelasi dengan diagnostik lain untuk kesalahan

Payload: kosong

Target Gagal

Target merespons tetapi responsnya tidak valid atau rusak

Kode Alasan:131

Status06A2:

Properti:

Nama	Tipe	Wajib	Deskripsi
reason	string	no	berisi informasi tentang apa yang secara khusus tidak valid tentang pesan

Payload: kosong

Waktu Target habis

kehabisan waktu untuk menunggu target untuk menyelesaikan permintaan

Kode Alasan:131

Status06A1:

Properti:

Nama	Tipe	Wajib	Deskripsi
trace-id	string	no	ID pelacakan untuk korelasi dengan diagnostik lain untuk kesalahan
reason	string	no	berisi informasi tentang apa yang secara khusus tidak valid tentang pesan

Payload: kosong

Target Tidak Tersedia

Target tidak dapat dijangkau untuk menyelesaikan permintaan

Kode Alasan:131

Status06A0:

Properti: tidak ada

Payload: kosong

Dibatasi

tingkat permintaan terlalu tinggi per SKU

Kode Alasan:151

Status0501:

Properti: tidak ada

Payload: kosong

Waktu habis

waktu operasi habis sebelum operasi selesai

Kode Alasan:131

Status0602:

Properti:

Nama	Tipe	Wajib	Deskripsi
trace-id	string	no	ID pelacakan untuk korelasi dengan diagnostik lain untuk kesalahan

Payload: kosong