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