Informazioni di riferimento sulle API MQTT 5 del piano dati hub IoT (deprecato)

  • Articolo

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

Richiedi

Nome argomento: $iothub/twin/get

Proprietà: nessuno

Payload: vuoto

Risposta riuscita

Proprietà: nessuno

Payload: Gemello

Risposte alternative

Status 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 Timeout 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

Richiedi

Nome argomento: $iothub/twin/patch/reported

Proprietà:

Nome Digita Obbligatorio Descrizione
if-version u64 no

Payload: TwinState

Risposta riuscita

Proprietà:

Nome Digita Obbligatorio Descrizione
versione u64 yes Versione dello stato segnalato dopo l'applicazione della patch

Payload: vuoto

Risposte alternative

Status 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 Timeout 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

Message

Nome argomento: $iothub/commands

Proprietà:

Nome Digita Obbligatorio Descrizione
sequence-no u64 yes Numero di sequenza del messaggio
tempo accodato Ora yes Timestamp di quando il messaggio è entrato nel sistema
delivery-count u32 yes Numero di tentativi di recapito del messaggio
creation-time Ora no Timestamp di quando il messaggio è stato creato (fornito dal mittente)
message-id string no Identità del messaggio (fornita dal mittente)
user-id string no Identità utente (fornita dal mittente)
correlation-id string no Identità di correlazione (fornita dal mittente)
Tipo di contenuto string no determina il tipo di contenuto del payload
content-encoding string 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 motivo Status 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 Rifiuto 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

Richiedi

Nome argomento: $iothub/methods/{name}

Proprietà: nessuno

Payload: qualsiasi sequenza di byte

Risposta riuscita

Proprietà:

Nome Digita Obbligatorio Descrizione
response-code u32 yes

Payload: qualsiasi sequenza di byte

Risposte alternative

Status Nome Descrizione
06A0 Non disponibile 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

Message

Nome argomento: $iothub/twin/patch/desired

Proprietà:

Nome Digita Obbligatorio Descrizione
versione u64 yes 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.

Message

Nome argomento: $iothub/telemetry

Proprietà:

Nome Digita Obbligatorio Descrizione
Tipo di contenuto string no converte in content-type proprietà di sistema nel messaggio pubblicato
content-encoding string no converte in content-encoding proprietà di sistema nel messaggio pubblicato
message-id string no converte in message-id proprietà di sistema nel messaggio pubblicato
user-id string no converte in user-id proprietà di sistema nel messaggio pubblicato
correlation-id string no converte in correlation-id proprietà di sistema nel messaggio pubblicato
creation-time Ora 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 motivo Status 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 Timeout 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 Digita Obbligatorio Descrizione
reason string 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 Digita Obbligatorio Descrizione
trace-id string no ID di traccia per la correlazione con altre diagnostica per l'errore
reason string 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 Digita Obbligatorio Descrizione
reason string 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 Digita Obbligatorio Descrizione
trace-id string 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 Digita Obbligatorio Descrizione
reason string 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 Digita Obbligatorio Descrizione
reason string 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 Digita Obbligatorio Descrizione
trace-id string 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 Digita Obbligatorio Descrizione
trace-id string 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 Digita Obbligatorio Descrizione
reason string 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 Digita Obbligatorio Descrizione
trace-id string no ID di traccia per la correlazione con altre diagnostica per l'errore
reason string 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

Timeout

timeout dell'operazione prima del completamento

Codice motivo: 131

Stato: 0602

Proprietà:

Nome Digita Obbligatorio Descrizione
trace-id string no ID di traccia per la correlazione con altre diagnostica per l'errore

Payload: vuoto