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