Compartilhar via

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

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

Observação

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

Operations

Obter gêmeo

Obter estado gêmeo

Solicitação

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

Propriedades: nenhuma

Carga: vazia

Resposta de êxito

Propriedades: nenhuma

Carga: Gêmeo

Respostas alternativas

Status Nome Descrição
0100 Solicitação incorreta A mensagem da 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 Acelerado a taxa de solicitação é muito alta por SKU
0502 Cota Excedida a cota diária por SKU atual foi excedida
0601 Erro de servidor erro interno do servidor
0602 Tempo limite a operação atingiu o tempo limite antes de 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 do gêmeo reportado

Estado do patch do gêmeo reportado

Solicitação

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

Propriedades:

Nome Digitar Obrigatória Descrição
if-version u64 não

Payload: TwinState

Resposta de êxito

Propriedades:

Nome Digitar Obrigatória Descrição
version u64 sim Versão do estado relatado após a aplicação do patch

Carga: vazia

Respostas alternativas

Status Nome Descrição
0104 Falha na Pré-condição a pré-condição não foi atendida, resultando no cancelamento da solicitação
0100 Solicitação incorreta A mensagem da 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 Acelerado a taxa de solicitação é muito alta por SKU
0502 Cota Excedida a cota diária por SKU atual foi excedida
0601 Erro de servidor erro interno do servidor
0602 Tempo limite a operação atingiu o tempo limite antes de 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 Digitar Obrigatória Descrição
sequence-no u64 sim Número de sequência da mensagem
enqueued-time time sim Carimbo de data/hora de quando a mensagem entrou no sistema
Contagem de entrega u32 sim Número de tentativas de entrega da mensagem
creation-time time não Carimbo de data/hora de quando a mensagem foi criada (fornecida pelo remetente)
message-id string não Identidade da mensagem (fornecida pelo remetente)
user-id string não Identidade do usuário (fornecida pelo remetente)
correlation-id string não Identidade de correlação (fornecida pelo remetente)
Tipo de conteúdo string não determina o Tipo de Conteúdo de payload
content-encoding string não determina a Codificação de Conteúdo de payload

Payload: qualquer sequência de bytes

Confirmação de sucesso

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

Propriedades: nenhuma

Carga: vazia

Confirmações alternativas

Código de motivo Status Nome Descrição
131 0603 Abandonar Indica que o comando não será processado neste momento e deverá ser entregue novamente no futuro.
131 0100 Rejeitar Indica que o cliente rejeitou o comando e que 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

Receber Métodos diretos

Receber e tratar Chamadas de método direto

Solicitação

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

Propriedades: nenhuma

Payload: qualquer sequência de bytes

Resposta de êxito

Propriedades:

Nome Digitar Obrigatória Descrição
response-code u32 sim

Payload: qualquer sequência de bytes

Respostas alternativas

Status Nome Descrição
06A0 Indisponível Indica que o cliente não pode ser alcançado 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 desejado do gêmeo

Receber atualizações para o estado desejado do gêmeo

Mensagem

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

Propriedades:

Nome Digitar Obrigatória Descrição
version u64 sim Versão do estado desejado que corresponde a esta atualização

Payload: 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 do Azure por padrão ou outro ponto de extremidade por meio da configuração de roteamento.

Mensagem

Nome do tópico: $iothub/telemetry

Propriedades:

Nome Digitar Obrigatória Descrição
Tipo de conteúdo string não converte em content-type propriedade do sistema na mensagem postada
content-encoding string não converte em content-encoding propriedade do sistema na mensagem postada
message-id string não converte em message-id propriedade do sistema na mensagem postada
user-id string não converte em user-id propriedade do sistema na mensagem postada
correlation-id string não converte em correlation-id propriedade do sistema na mensagem postada
creation-time time não converte em iothub-creation-time-utc propriedade do sistema na mensagem postada

Dica

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

Payload: qualquer sequência de bytes

Confirmação de sucesso

A mensagem foi postada com êxito no canal de telemetria

Propriedades: nenhuma

Carga: vazia

Confirmações alternativas

Código de motivo Status Nome Descrição
131 0100 Solicitação incorreta A mensagem da 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 de servidor erro interno do servidor
151 0501 Acelerado a taxa de solicitação é muito alta por SKU
151 0502 Cota Excedida a cota diária por SKU atual foi excedida
131 0602 Tempo limite a operação atingiu o tempo limite antes de 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

Solicitação incorreta

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

Código do motivo: 131

Status: 0100

Propriedades:

Nome Digitar Obrigatória Descrição
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga: vazia

Conflito

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

Código do motivo: 131

Status: 0103

Propriedades:

Nome Digitar Obrigatória Descrição
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: vazia

Não Permitido

A operação não é permitida.

Código do motivo: 131

Status: 0102

Propriedades:

Nome Digitar Obrigatória Descrição
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga: vazia

Não autorizado

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

Código do motivo: 135

Status: 0101

Propriedades:

Nome Digitar Obrigatória Descrição
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga: vazia

Não encontrado

o recurso solicitado não existe

Código do motivo: 131

Status: 0504

Propriedades:

Nome Digitar Obrigatória Descrição
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga: vazia

Não modificado

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

Código do motivo: 0

Status: 0001

Propriedades: nenhuma

Carga: vazia

Falha na Pré-condição

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

Código do motivo: 131

Status: 0104

Propriedades: nenhuma

Carga: vazia

Cota Excedida

a cota diária por SKU atual foi excedida

Código do motivo: 151

Status: 0502

Propriedades: nenhuma

Carga: vazia

Recurso Esgotado

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

Código do motivo: 131

Status: 0503

Propriedades:

Nome Digitar Obrigatória Descrição
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga: vazia

Servidor ocupado

servidor ocupado

Código do motivo: 131

Status: 0603

Propriedades:

Nome Digitar Obrigatória Descrição
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga: vazia

Erro de servidor

erro interno do servidor

Código do motivo: 131

Status: 0601

Propriedades:

Nome Digitar Obrigatória Descrição
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga: vazia

Falha no destino

O destino respondeu, mas a resposta era inválida ou malformada

Código do motivo: 131

Status: 06A2

Propriedades:

Nome Digitar Obrigatória Descrição
reason string não contém informações sobre o que especificamente não é válido sobre a mensagem

Carga: vazia

Tempo limite de destino

tempo limite excedido ao aguardar o destino concluir a solicitação

Código do motivo: 131

Status: 06A1

Propriedades:

Nome Digitar Obrigatória Descrição
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: vazia

Destino não disponível

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

Código do motivo: 131

Status: 06A0

Propriedades: nenhuma

Carga: vazia

Acelerado

a taxa de solicitação é muito alta por SKU

Código do motivo: 151

Status: 0501

Propriedades: nenhuma

Carga: vazia

Tempo limite

a operação atingiu o tempo limite antes de ser concluída

Código do motivo: 131

Status: 0602

Propriedades:

Nome Digitar Obrigatória Descrição
trace-id string não ID de rastreamento para correlação com outros diagnósticos para o erro

Carga: vazia