Partilhar via

Referência da API MQTT 5 do plano de dados do Hub IoT (preterido)

  • Artigo

Este documento define as operações disponíveis na versão 2.0 (api-version: 2020-10-01-preview) da API do plano de dados do Hub IoT.

Nota

O suporte ao MQTT 5 no Hub IoT foi preterido e o Hub IoT tem suporte limitado a recursos para MQTT. Se sua solução precisar de suporte a MQTT v3.1.1 ou v5, recomendamos o suporte a MQTT na Grade de Eventos do Azure. Para obter mais informações, consulte Comparar o suporte MQTT no Hub IoT e na Grade de Eventos.

Operações

Obter Twin

Obter estado Twin

Pedir

Nome do tópico: $iothub/twin/get

Propriedades: nenhuma

Carga útil: vazia

Resposta de sucesso

Propriedades: nenhuma

Carga útil: Twin

Respostas alternativas

Status Nome Descrição
0100 Pedido Incorreto A mensagem de operação está malformada e não pode ser processada.
0101 Não Autorizado O cliente não está autorizado a executar a operação.
0102 Não permitido A operação não é permitida.
0501 Limitado taxa de solicitação é muito alta por SKU
0502 Quota Excedida a cota diária por SKU atual é excedida
0601 Erro do Servidor Erro interno do servidor
0602 Limite de tempo excedido a operação expirou antes de poder ser concluída
0603 Servidor ocupado Servidor ocupado

Exemplo de pseudocódigo


-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Patch Twin Relatado

Estado relatado do Patch Twin

Pedir

Nome do tópico: $iothub/twin/patch/reported

Propriedades:

Nome Type Obrigatório Description
if-versão U64 não

Carga útil: TwinState

Resposta de sucesso

Propriedades:

Nome Type Obrigatório Description
versão U64 sim Versão do estado relatado após a aplicação do patch

Carga útil: vazia

Respostas alternativas

Status Nome Descrição
0104 Falha na pré-condição A pré-condição não foi cumprida, resultando no cancelamento da solicitação
0100 Pedido Incorreto A mensagem de operação está malformada e não pode ser processada.
0101 Não Autorizado O cliente não está autorizado a executar a operação.
0102 Não permitido A operação não é permitida.
0501 Limitado taxa de solicitação é muito alta por SKU
0502 Quota Excedida a cota diária por SKU atual é excedida
0601 Erro do Servidor Erro interno do servidor
0602 Limite de tempo excedido a operação expirou antes de poder ser concluída
0603 Servidor ocupado Servidor ocupado

Exemplo de pseudocódigo


-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/reported
    [if-version: <u64>]
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Receber comandos

Receber e manipular comandos

Mensagem

Nome do tópico: $iothub/commands

Propriedades:

Nome Type Obrigatório Description
sequência-não U64 sim Número de sequência da mensagem
tempo enfileirado hora sim Carimbo de data/hora de quando a mensagem entrou no sistema
contagem de entregas Sub-32 sim Número de vezes que a entrega da mensagem foi tentada
tempo de criação hora não Carimbo de data/hora de quando a mensagem foi criada (fornecido pelo remetente)
ID da mensagem string não Identidade da mensagem (fornecida pelo remetente)
ID de utilizador string não Identidade do usuário (fornecida pelo remetente)
Correlação-ID string não Identidade de correlação (fornecida pelo remetente)
Tipo de conteúdo string não determina o tipo de conteúdo da carga útil
codificação de conteúdo string não determina a codificação de conteúdo da carga útil

Carga útil: qualquer sequência de bytes

Reconhecimento de Sucesso

Indica que o comando foi aceito para manipulação pelo cliente

Propriedades: nenhuma

Carga útil: vazia

Agradecimentos Alternativos

Código da Razão Status Nome Descrição
131 0603 Abandonar Indica que o comando não será processado neste momento e deve ser entregue novamente no futuro.
131 0100 Rejeitar Indica que o cliente rejeitou o comando e ele não deve ser tentado novamente.

Exemplo de pseudocódigo


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

Receba métodos diretos

Receber e lidar com chamadas do Método Direto

Pedir

Nome do tópico: $iothub/methods/{name}

Propriedades: nenhuma

Carga útil: qualquer sequência de bytes

Resposta de sucesso

Propriedades:

Nome Type Obrigatório Description
código de resposta Sub-32 sim

Carga útil: qualquer sequência de bytes

Respostas alternativas

Status Nome Descrição
06A0 Indisponível Indica que o cliente não pode ser acessado por meio dessa conexão.

Exemplo de pseudocódigo


-> SUBSCRIBE
    - Topic: methods/{name}
      QoS: 0
<- SUBACK
<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/{name}
-> PUBLISH
    QoS: 0
    Topic: $iothub/responses

Receber alterações de estado desejadas gêmeas

Receba atualizações para o estado desejado do Twin

Mensagem

Nome do tópico: $iothub/twin/patch/desired

Propriedades:

Nome Type Obrigatório Description
versão U64 sim Versão do estado desejado correspondente a esta atualização

Carga útil: TwinState

Exemplo de pseudocódigo


-> SUBSCRIBE
    - Topic: $iothub/twin/patch/desired
      QoS: 0
<- PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/desired
    version: <u64>
    Payload: ...

Enviar Telemetria

Postar mensagem no canal de telemetria - Hubs de Eventos por padrão ou outro ponto de extremidade por meio da configuração de roteamento.

Mensagem

Nome do tópico: $iothub/telemetry

Propriedades:

Nome Type Obrigatório Description
Tipo de conteúdo string não Traduz em content-type propriedade do sistema na mensagem postada
codificação de conteúdo string não Traduz em content-encoding propriedade do sistema na mensagem postada
ID da mensagem string não Traduz em message-id propriedade do sistema na mensagem postada
ID de utilizador string não Traduz em user-id propriedade do sistema na mensagem postada
Correlação-ID string não Traduz em correlation-id propriedade do sistema na mensagem postada
tempo de criação hora não se traduz em iothub-creation-time-utc propriedade na mensagem postada

Gorjeta

O formato de deve ser UTC sem informações de creation-time fuso horário. Por exemplo, 2021-04-21T11:30:16Z é válido, 2021-04-21T11:30:16-07:00 é inválido.

Carga útil: qualquer sequência de bytes

Reconhecimento de Sucesso

A mensagem foi postada com sucesso no canal de telemetria

Propriedades: nenhuma

Carga útil: vazia

Agradecimentos Alternativos

Código da Razão Status Nome Descrição
131 0100 Pedido Incorreto A mensagem de operação está malformada e não pode ser processada.
135 0101 Não Autorizado O cliente não está autorizado a executar a operação.
131 0102 Não permitido A operação não é permitida.
131 0601 Erro do Servidor Erro interno do servidor
151 0501 Limitado taxa de solicitação é muito alta por SKU
151 0502 Quota Excedida a cota diária por SKU atual é excedida
131 0602 Limite de tempo excedido a operação expirou antes de poder ser concluída
131 0603 Servidor ocupado Servidor ocupado

Exemplo de pseudocódigo

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

Respostas

Pedido Incorreto

A mensagem de operação está malformada e não pode ser processada.

Código da razão: 131

Estado: 0100

Propriedades:

Nome Type Obrigatório Description
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga útil: vazia

Conflito

A operação está em conflito com outra operação em curso.

Código da razão: 131

Estado: 0103

Propriedades:

Nome Type Obrigatório Description
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga útil: vazia

Não permitido

A operação não é permitida.

Código da razão: 131

Estado: 0102

Propriedades:

Nome Type Obrigatório Description
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga útil: vazia

Não Autorizado

O cliente não está autorizado a executar a operação.

Código da razão: 135

Estado: 0101

Propriedades:

Nome Type Obrigatório Description
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga útil: vazia

Não Encontrado

O recurso solicitado não existe

Código da razão: 131

Estado: 0504

Propriedades:

Nome Type Obrigatório Description
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga útil: vazia

Não modificado

O recurso não foi modificado com base na pré-condição fornecida.

Código da razão: 0

Estado: 0001

Propriedades: nenhuma

Carga útil: vazia

Falha na pré-condição

A pré-condição não foi atendida, resultando no cancelamento da solicitação

Código da razão: 131

Estado: 0104

Propriedades: nenhuma

Carga útil: vazia

Quota Excedida

a cota diária por SKU atual é excedida

Código da razão: 151

Estado: 0502

Propriedades: nenhuma

Carga útil: vazia

Recursos esgotados

recurso não tem capacidade para concluir a operação

Código da razão: 131

Estado: 0503

Propriedades:

Nome Type Obrigatório Description
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga útil: vazia

Servidor ocupado

Servidor ocupado

Código da razão: 131

Estado: 0603

Propriedades:

Nome Type Obrigatório Description
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga útil: vazia

Erro do Servidor

Erro interno do servidor

Código da razão: 131

Estado: 0601

Propriedades:

Nome Type Obrigatório Description
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga útil: vazia

Alvo falhou

O alvo respondeu, mas a resposta foi inválida ou malformada

Código da razão: 131

Estado: 06A2

Propriedades:

Nome Type Obrigatório Description
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga útil: vazia

Tempo limite de destino

Tempo limite de espera que o destino conclua a solicitação

Código da razão: 131

Estado: 06A1

Propriedades:

Nome Type Obrigatório Description
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga útil: vazia

Alvo indisponível

O destino está inacessível para concluir a solicitação

Código da razão: 131

Estado: 06A0

Propriedades: nenhuma

Carga útil: vazia

Limitado

taxa de solicitação é muito alta por SKU

Código da razão: 151

Estado: 0501

Propriedades: nenhuma

Carga útil: vazia

Limite de tempo excedido

a operação expirou antes de poder ser concluída

Código da razão: 131

Estado: 0602

Propriedades:

Nome Type Obrigatório Description
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga útil: vazia