Referensi API MQTT 5 sarana data IoT Hub

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

Operasional

Mendapatkan kembaran

Mendapatkan status kembaran

Minta

Nama topik:$iothub/twin/get

Properti: tidak ada

Payload: kosong

Respons Keberhasilan

Properti: tidak ada

Payload: Kembar

Respons Alternatif

Status	Nama	Deskripsi
0100	Permintaan Buruk	Pesan operasi rusak dan tidak dapat diproses.
0101	Tidak Diizinkan	Klien tidak diizinkan untuk melakukan operasi.
0102	Tidak Diperbolehkan	Operasi tidak diizinkan.
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	Batas waktu	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

Minta

Nama topik:$iothub/twin/patch/reported

Properti:

Nama	Jenis	Diperlukan	Deskripsi
if-version	u64	tidak

Payload: TwinState

Respons Keberhasilan

Properti:

Nama	Jenis	Diperlukan	Deskripsi
versi	u64	ya	Versi status yang dilaporkan setelah patch diterapkan

Payload: kosong

Respons Alternatif

Status	Nama	Deskripsi
0104	Prasyarat gagal	prasyarat tidak terpenuhi sehingga permintaan dibatalkan
0100	Permintaan Buruk	Pesan operasi rusak dan tidak dapat diproses.
0101	Tidak Diizinkan	Klien tidak diizinkan untuk melakukan operasi.
0102	Tidak Diperbolehkan	Operasi tidak diizinkan.
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	Batas waktu	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	Jenis	Diperlukan	Deskripsi
sequence-no	u64	ya	Mengurutkan nomor pesan
enqueued-time	waktu	ya	Tanda waktu ketika pesan memasuki sistem
delivery-count	u32	ya	Jumlah percobaan pengiriman pesan telah dilakukan
creation-time	waktu	tidak	Tanda waktu saat pesan dibuat (disediakan oleh pengirim)
message-id	untai (karakter)	tidak	Identitas pesan (disediakan oleh pengirim)
user_id	string	tidak	Identitas pengguna (disediakan oleh pengirim)
correlation-id	untai (karakter)	tidak	Identitas korelasi (disediakan oleh pengirim)
Jenis Konten	string	tidak	menentukan Jenis Konten payload
content-encoding	string	tidak	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	Status	Nama	Deskripsi
131	0603	Tinggalkan	Menunjukkan bahwa perintah tidak akan diproses saat ini dan harus dikirim ulang di waktu yang akan datang.
131	0100	Tolak	Menunjukkan bahwa perintah ditolak oleh klien 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

Minta

Nama topik:$iothub/methods/{name}

Properti: tidak ada

Payload: urutan byte apapun

Respons Keberhasilan

Properti:

Nama	Jenis	Diperlukan	Deskripsi
response-code	u32	ya

Payload: urutan byte apapun

Respons Alternatif

Status	Nama	Deskripsi
06A0	Tidak tersedia	Menunjukkan bahwa klien tidak dapat dijangkau melalui sambungan 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	Jenis	Diperlukan	Deskripsi
versi	u64	ya	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

Memosting pesan ke saluran telemetri - EventHubs secara default atau titik akhir lainnya melalui konfigurasi perutean.

Pesan

Nama topik:$iothub/telemetry

Properti:

Nama	Jenis	Diperlukan	Deskripsi
Jenis Konten	string	tidak	menerjemahkan ke dalam properti sistem content-type pada pesan yang diposting
content-encoding	string	tidak	menerjemahkan ke dalam properti sistem content-encoding pada pesan yang diposting
message-id	untai (karakter)	tidak	menerjemahkan ke dalam properti sistem message-id pada pesan yang diposting
user_id	string	tidak	menerjemahkan ke dalam properti sistem user-id pada pesan yang diposting
correlation-id	untai (karakter)	tidak	menerjemahkan ke dalam properti sistem correlation-id pada pesan yang diposting
creation-time	waktu	tidak	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	Status	Nama	Deskripsi
131	0100	Permintaan Buruk	Pesan operasi rusak dan tidak dapat diproses.
135	0101	Tidak Diizinkan	Klien tidak diizinkan untuk melakukan operasi.
131	0102	Tidak Diperbolehkan	Operasi tidak diizinkan.
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	Batas waktu	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 rusak dan tidak dapat diproses.

Kode Alasan:131

Status:0100

Properti:

Nama	Jenis	Diperlukan	Deskripsi
reason	string	tidak	berisi informasi, khususnya tentang apa yang tidak valid tentang pesannya

Payload: kosong

Konflik

Operasi bertentangan dengan operasi lain yang sedang berlangsung.

Kode Alasan:131

Status:0103

Properti:

Nama	Jenis	Diperlukan	Deskripsi
trace-id	string	tidak	melacak ID untuk korelasi dengan diagnostik tambahan untuk kesalahan
reason	string	tidak	berisi informasi, khususnya tentang apa yang tidak valid tentang pesannya

Payload: kosong

Tidak Diperbolehkan

Operasi tidak diizinkan.

Kode Alasan:131

Status:0102

Properti:

Nama	Jenis	Diperlukan	Deskripsi
reason	string	tidak	berisi informasi, khususnya tentang apa yang tidak valid tentang pesannya

Payload: kosong

Tidak Diizinkan

Klien tidak diizinkan untuk melakukan operasi.

Kode Alasan:135

Status:0101

Properti:

Nama	Jenis	Diperlukan	Deskripsi
trace-id	string	tidak	melacak ID untuk korelasi dengan diagnostik tambahan untuk kesalahan

Payload: kosong

Tidak Ditemukan

sumber daya yang diminta tidak ada

Kode Alasan:131

Status:0504

Properti:

Nama	Jenis	Diperlukan	Deskripsi
reason	string	tidak	berisi informasi, khususnya tentang apa yang tidak valid tentang pesannya

Payload: kosong

Tidak Diubah

Sumber daya tidak dimodifikasi berdasarkan pada prasyarat yang disediakan.

Kode Alasan:0

Status:0001

Properti: tidak ada

Payload: kosong

Prasyarat gagal

Prasyarat tidak terpenuhi sehingga permintaan dibatalkan

Kode Alasan:131

Status:0104

Properti: tidak ada

Payload: kosong

Kuota Terlampaui

kuota harian per SKU saat ini terlampaui

Kode Alasan:151

Status:0502

Properti: tidak ada

Payload: kosong

Sumber Daya Telah Habis

sumber daya kehabisan kapasitas untuk menyelesaikan operasi

Kode Alasan:131

Status:0503

Properti:

Nama	Jenis	Diperlukan	Deskripsi
reason	string	tidak	berisi informasi, khususnya tentang apa yang tidak valid tentang pesannya

Payload: kosong

Server Sibuk

server sibuk

Kode Alasan:131

Status:0603

Properti:

Nama	Jenis	Diperlukan	Deskripsi
trace-id	string	tidak	melacak ID untuk korelasi dengan diagnostik tambahan untuk kesalahan

Payload: kosong

Kesalahan Server

kesalahan server internal

Kode Alasan:131

Status:0601

Properti:

Nama	Jenis	Diperlukan	Deskripsi
trace-id	string	tidak	melacak ID untuk korelasi dengan diagnostik tambahan untuk kesalahan

Payload: kosong

Target Gagal

Target merespons tetapi responsnya tidak valid atau rusak

Kode Alasan:131

Status:06A2

Properti:

Nama	Jenis	Diperlukan	Deskripsi
reason	string	tidak	berisi informasi, khususnya tentang apa yang tidak valid tentang pesannya

Payload: kosong

Waktu Target habis

kehabisan waktu untuk menunggu target untuk menyelesaikan permintaan

Kode Alasan:131

Status:06A1

Properti:

Nama	Jenis	Diperlukan	Deskripsi
trace-id	string	tidak	melacak ID untuk korelasi dengan diagnostik tambahan untuk kesalahan
reason	string	tidak	berisi informasi, khususnya tentang apa yang tidak valid tentang pesannya

Payload: kosong

Target Tidak Tersedia

Target tidak dapat dijangkau untuk menyelesaikan permintaan

Kode Alasan:131

Status:06A0

Properti: tidak ada

Payload: kosong

Dibatasi

tingkat permintaan terlalu tinggi per SKU

Kode Alasan:151

Status:0501

Properti: tidak ada

Payload: kosong

Batas waktu

waktu operasi habis sebelum operasi selesai

Kode Alasan:131

Status:0602

Properti:

Nama	Jenis	Diperlukan	Deskripsi
trace-id	string	tidak	melacak ID untuk korelasi dengan diagnostik tambahan untuk kesalahan

Payload: kosong