Informazioni di riferimento sulle API MQTT 5 del piano dati hub IoT (deprecato)
Questo documento definisce le operazioni disponibili nella versione 2.0 (api-version: 2020-10-01-preview
) dell'API del piano dati di hub IoT.
Nota
Il supporto di MQTT 5 in hub IoT è deprecato e hub IoT supporta funzionalità limitate per MQTT. Se la soluzione richiede il supporto MQTT v3.1.1 o v5, è consigliabile supportare MQTT in Griglia di eventi di Azure. Per altre informazioni, vedere Confrontare il supporto MQTT in hub IoT e Griglia di eventi.
Operazioni
Ottieni gemello
Ottenere lo stato del dispositivo gemello
Richiesta
Nome argomento:$iothub/twin/get
Proprietà: nessuno
Payload: vuoto
Risposta riuscita
Proprietà: nessuno
Payload: Gemello
Risposte alternative
Stato | Nome | Descrizione |
---|---|---|
0100 | Richiesta non valida | Il messaggio dell'operazione non è valido e non può essere elaborato. |
0101 | Non autorizzato | Il client non è autorizzato a eseguire l'operazione. |
0102 | Non consentito | L'operazione non è consentita. |
0501 | Sospensione causata dal servizio Microsoft FullText | la frequenza delle richieste è troppo elevata per OGNI SKU |
0502 | Quota superata | quota giornaliera per SKU corrente superata |
0601 | Errore del server | errore interno del server |
0602 | Interruzione | timeout dell'operazione prima del completamento |
0603 | Server occupato | server occupato |
Esempio di pseudo-codice
-> PUBLISH
QoS: 0
Topic: $iothub/twin/get
<- PUBLISH
QoS: 0
Topic: $iothub/responses
Patch Twin Segnalata
Stato segnalato di Patch Twin
Richiesta
Nome argomento:$iothub/twin/patch/reported
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
if-version | u64 | no |
Payload: TwinState
Risposta riuscita
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
Versione | u64 | Sì | Versione dello stato segnalato dopo l'applicazione della patch |
Payload: vuoto
Risposte alternative
Stato | Nome | Descrizione |
---|---|---|
0104 | Precondizione non riuscita | precondizione non è stata soddisfatta con conseguente annullamento della richiesta |
0100 | Richiesta non valida | Il messaggio dell'operazione non è valido e non può essere elaborato. |
0101 | Non autorizzato | Il client non è autorizzato a eseguire l'operazione. |
0102 | Non consentito | L'operazione non è consentita. |
0501 | Sospensione causata dal servizio Microsoft FullText | la frequenza delle richieste è troppo elevata per OGNI SKU |
0502 | Quota superata | quota giornaliera per SKU corrente superata |
0601 | Errore del server | errore interno del server |
0602 | Interruzione | timeout dell'operazione prima del completamento |
0603 | Server occupato | server occupato |
Esempio di pseudo-codice
-> PUBLISH
QoS: 0
Topic: $iothub/twin/patch/reported
[if-version: <u64>]
<- PUBLISH
QoS: 0
Topic: $iothub/responses
Comandi di ricezione
Ricevere e gestire i comandi
Messaggio
Nome argomento:$iothub/commands
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
sequence-no | u64 | Sì | Numero di sequenza del messaggio |
tempo accodato | tempo | Sì | Timestamp di quando il messaggio è entrato nel sistema |
delivery-count | u32 | Sì | Numero di tentativi di recapito del messaggio |
creation-time | tempo | no | Timestamp di quando il messaggio è stato creato (fornito dal mittente) |
ID messaggio | corda | no | Identità del messaggio (fornita dal mittente) |
ID utente | corda | no | Identità utente (fornita dal mittente) |
ID di correlazione | corda | no | Identità di correlazione (fornita dal mittente) |
Tipo di contenuto | corda | no | determina il tipo di contenuto del payload |
content-encoding | corda | no | determina la codifica del contenuto del payload |
Payload: qualsiasi sequenza di byte
Riconoscimento dell'esito positivo
Indica che il comando è stato accettato per la gestione da parte del client
Proprietà: nessuno
Payload: vuoto
Riconoscimenti alternativi
Codice causale | Stato | Nome | Descrizione |
---|---|---|---|
131 | 0603 | Abbandono | Indica che il comando non verrà elaborato in questo momento e dovrebbe essere recapitato di nuovo in futuro. |
131 | 0100 | Rifiutare | Indica che il client ha rifiutato il comando e non deve essere provato di nuovo. |
Esempio di pseudo-codice
-> 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
Ricevere metodi diretti
Ricevere e gestire chiamate al metodo diretto
Richiesta
Nome argomento:$iothub/methods/{name}
Proprietà: nessuno
Payload: qualsiasi sequenza di byte
Risposta riuscita
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
response-code | u32 | Sì |
Payload: qualsiasi sequenza di byte
Risposte alternative
Stato | Nome | Descrizione |
---|---|---|
06A0 | Indisponibile | Indica che il client non è raggiungibile tramite questa connessione. |
Esempio di pseudo-codice
-> SUBSCRIBE
- Topic: methods/{name}
QoS: 0
<- SUBACK
<- PUBLISH
QoS: 0
Topic: $iothub/methods/{name}
-> PUBLISH
QoS: 0
Topic: $iothub/responses
Ricevere modifiche dello stato desiderato del dispositivo gemello
Ricevere gli aggiornamenti allo stato desiderato di Twin
Messaggio
Nome argomento:$iothub/twin/patch/desired
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
Versione | u64 | Sì | Versione dello stato desiderato corrispondente a questo aggiornamento |
Payload: TwinState
Esempio di pseudo-codice
-> SUBSCRIBE
- Topic: $iothub/twin/patch/desired
QoS: 0
<- PUBLISH
QoS: 0
Topic: $iothub/twin/patch/desired
version: <u64>
Payload: ...
Inviare dati di telemetria
Inviare un messaggio al canale di telemetria: Hub eventi per impostazione predefinita o altri endpoint tramite la configurazione del routing.
Messaggio
Nome argomento:$iothub/telemetry
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
Tipo di contenuto | corda | no | converte in content-type proprietà di sistema nel messaggio pubblicato |
content-encoding | corda | no | converte in content-encoding proprietà di sistema nel messaggio pubblicato |
ID messaggio | corda | no | converte in message-id proprietà di sistema nel messaggio pubblicato |
ID utente | corda | no | converte in user-id proprietà di sistema nel messaggio pubblicato |
ID di correlazione | corda | no | converte in correlation-id proprietà di sistema nel messaggio pubblicato |
creation-time | tempo | no | converte in iothub-creation-time-utc proprietà nel messaggio pubblicato |
Suggerimento
Il formato di creation-time
deve essere UTC senza informazioni sul fuso orario. Ad esempio, 2021-04-21T11:30:16Z
è valido e 2021-04-21T11:30:16-07:00
non è valido.
Payload: qualsiasi sequenza di byte
Riconoscimento dell'esito positivo
Il messaggio è stato pubblicato correttamente nel canale di telemetria
Proprietà: nessuno
Payload: vuoto
Riconoscimenti alternativi
Codice causale | Stato | Nome | Descrizione |
---|---|---|---|
131 | 0100 | Richiesta non valida | Il messaggio dell'operazione non è valido e non può essere elaborato. |
135 | 0101 | Non autorizzato | Il client non è autorizzato a eseguire l'operazione. |
131 | 0102 | Non consentito | L'operazione non è consentita. |
131 | 0601 | Errore del server | errore interno del server |
151 | 0501 | Sospensione causata dal servizio Microsoft FullText | la frequenza delle richieste è troppo elevata per OGNI SKU |
151 | 0502 | Quota superata | quota giornaliera per SKU corrente superata |
131 | 0602 | Interruzione | timeout dell'operazione prima del completamento |
131 | 0603 | Server occupato | server occupato |
Esempio di pseudo-codice
-> 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
Risposte
Richiesta non valida
Il messaggio dell'operazione non è valido e non può essere elaborato.
Codice motivo:131
Stato:0100
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
motivo | corda | no | contiene informazioni su ciò che in particolare non è valido sul messaggio |
Payload: vuoto
Conflitto
L'operazione è in conflitto con un'altra operazione in corso.
Codice motivo:131
Stato:0103
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
trace-id | corda | no | ID di traccia per la correlazione con altre diagnostica per l'errore |
motivo | corda | no | contiene informazioni su ciò che in particolare non è valido sul messaggio |
Payload: vuoto
Non consentito
L'operazione non è consentita.
Codice motivo:131
Stato:0102
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
motivo | corda | no | contiene informazioni su ciò che in particolare non è valido sul messaggio |
Payload: vuoto
Non autorizzato
Il client non è autorizzato a eseguire l'operazione.
Codice motivo:135
Stato:0101
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
trace-id | corda | no | ID di traccia per la correlazione con altre diagnostica per l'errore |
Payload: vuoto
Non trovato
la risorsa richiesta non esiste
Codice motivo:131
Stato:0504
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
motivo | corda | no | contiene informazioni su ciò che in particolare non è valido sul messaggio |
Payload: vuoto
Non modificato
La risorsa non è stata modificata in base alla precondizione fornita.
Codice motivo:0
Stato:0001
Proprietà: nessuno
Payload: vuoto
Precondizione non riuscita
La precondizione non è stata soddisfatta con conseguente annullamento della richiesta
Codice motivo:131
Stato:0104
Proprietà: nessuno
Payload: vuoto
Quota superata
quota giornaliera per SKU corrente superata
Codice motivo:151
Stato:0502
Proprietà: nessuno
Payload: vuoto
Risorsa esaurita
la risorsa non ha capacità di completare l'operazione
Codice motivo:131
Stato:0503
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
motivo | corda | no | contiene informazioni su ciò che in particolare non è valido sul messaggio |
Payload: vuoto
Server occupato
server occupato
Codice motivo:131
Stato:0603
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
trace-id | corda | no | ID di traccia per la correlazione con altre diagnostica per l'errore |
Payload: vuoto
Errore del server
errore interno del server
Codice motivo:131
Stato:0601
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
trace-id | corda | no | ID di traccia per la correlazione con altre diagnostica per l'errore |
Payload: vuoto
Destinazione non riuscita
Destinazione ha risposto ma la risposta non è valida o non è valida
Codice motivo:131
Stato:06A2
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
motivo | corda | no | contiene informazioni su ciò che in particolare non è valido sul messaggio |
Payload: vuoto
Timeout di destinazione
timeout in attesa del completamento della richiesta da parte della destinazione
Codice motivo:131
Stato:06A1
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
trace-id | corda | no | ID di traccia per la correlazione con altre diagnostica per l'errore |
motivo | corda | no | contiene informazioni su ciò che in particolare non è valido sul messaggio |
Payload: vuoto
Destinazione non disponibile
La destinazione non è raggiungibile per completare la richiesta
Codice motivo:131
Stato:06A0
Proprietà: nessuno
Payload: vuoto
Sospensione causata dal servizio Microsoft FullText
la frequenza delle richieste è troppo elevata per OGNI SKU
Codice motivo:151
Stato:0501
Proprietà: nessuno
Payload: vuoto
Interruzione
timeout dell'operazione prima del completamento
Codice motivo:131
Stato:0602
Proprietà:
Nome | TIPO | Obbligatorio | Descrizione |
---|---|---|---|
trace-id | corda | no | ID di traccia per la correlazione con altre diagnostica per l'errore |
Payload: vuoto