Compartir vía

Referencia de la API MQTT 5 del plano de datos de IoT Hub (en desuso)

  • Artículo

En este documento se definen las operaciones disponibles en la versión 2.0 (api-version: 2020-10-01-preview) de la API del plano de datos de IoT Hub.

Nota:

La compatibilidad con MQTT 5 en IoT Hub está en desuso y IoT Hub tiene compatibilidad limitada con características para MQTT. Si la solución necesitase compatibilidad con MQTT v3.1.1 o v5, se recomienda la compatibilidad con MQTT en Azure Event Grid. Para más información, consulte Comparación de la compatibilidad con MQTT en IoT Hub y Event Grid.

Operations

Get Twin

Estado de Get Twin

Solicitar

Nombre del tema: $iothub/twin/get

Propiedades: ninguna

Carga útil: vacía

Respuesta de acción correcta

Propiedades: ninguna

Carga útil: Gemelo

Respuestas alternativas

Estado Nombre Descripción
0100 Bad Request El mensaje de la operación tiene un formato incorrecto y no se puede procesar.
0101 No autorizado El cliente no tiene autorización para realizar la operación.
0102 No permitida La operación no está permitida.
0501 Limitado La tasa de solicitudes es demasiado alta por SKU.
0502 Cuota superada Se superó la cuota diaria por SKU actual.
0601 Error de servidor Error interno del servidor.
0602 Tiempo de espera Se agotó el tiempo de espera de la operación antes de que pudiera completarse.
0603 Servidor ocupado Servidor ocupado.

Ejemplo de pseudocódigo


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

Operación Patch Twin notificada

Estado notificado de Patch Twin

Solicitar

Nombre del tema: $iothub/twin/patch/reported

Propiedades:

Nombre Type Obligatorio Descripción
if-version u64 no

Carga útil: TwinState

Respuesta de acción correcta

Propiedades:

Nombre Type Obligatorio Descripción
version u64 sí Versión de estado notificado después de aplicar la revisión.

Carga útil: vacía

Respuestas alternativas

Estado Nombre Descripción
0104 Error en la condición previa No se cumplió la condición previa, lo que provocó la cancelación de la solicitud
0100 Bad Request El mensaje de la operación tiene un formato incorrecto y no se puede procesar.
0101 No autorizado El cliente no tiene autorización para realizar la operación.
0102 No permitida La operación no está permitida.
0501 Limitado La tasa de solicitudes es demasiado alta por SKU.
0502 Cuota superada Se superó la cuota diaria por SKU actual.
0601 Error de servidor Error interno del servidor.
0602 Tiempo de espera Se agotó el tiempo de espera de la operación antes de que pudiera completarse.
0603 Servidor ocupado Servidor ocupado.

Ejemplo de pseudocódigo


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

Recepción de comandos

Recepción y control de comandos

Mensaje

Nombre del tema: $iothub/commands

Propiedades:

Nombre Type Obligatorio Descripción
sequence-no u64 sí Número de secuencia del mensaje.
enqueued-time time sí Marca de tiempo de la entrada del mensaje en el sistema.
delivery-count u32 sí Número de veces que se intentó la entrega del mensaje.
creation-time time no Marca de tiempo de creación del mensaje (proporcionada por el remitente).
message-id string no Identidad del mensaje (proporcionada por el remitente).
user-id string no Identidad de usuario (proporcionada por el remitente).
correlation-id string no Identidad de correlación (proporcionada por el remitente).
Tipo de contenido string no Determina el tipo de contenido de la carga útil.
content-encoding string no Determina la codificación de contenido de la carga útil.

Carga útil: cualquier secuencia de bytes

Reconocimiento de acción correcta

Indica que el cliente aceptó el comando para controlarlo.

Propiedades: ninguna

Carga útil: vacía

Reconocimientos alternativos

Código de motivo Estado Nombre Descripción
131 0603 Abandon Indica que el comando no se procesará en este momento y que debe volver a entregarse en el futuro.
131 0100 Reject Indica que el cliente rechazó el comando y no debe intentarse de nuevo.

Ejemplo 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

Recepción de métodos directos

Recepción y control de llamadas a métodos directos

Solicitar

Nombre del tema: $iothub/methods/{name}

Propiedades: ninguna

Carga útil: cualquier secuencia de bytes

Respuesta de acción correcta

Propiedades:

Nombre Type Obligatorio Descripción
response-code u32 sí

Carga útil: cualquier secuencia de bytes

Respuestas alternativas

Estado Nombre Descripción
06A0 No disponible Indica que el cliente no es accesible a través de esta conexión.

Ejemplo de pseudocódigo


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

Recepción de cambios de estado deseados del gemelo

Recibir actualizaciones del estado deseado del gemelo

Mensaje

Nombre del tema: $iothub/twin/patch/desired

Propiedades:

Nombre Type Obligatorio Descripción
version u64 sí Versión del estado deseado coincidente con esta actualización.

Carga útil: TwinState

Ejemplo de pseudocódigo


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

Envío de telemetría

Publicación del mensaje en el canal de telemetría: EventHubs de forma predeterminada u otro punto de conexión a través de la configuración de enrutamiento.

Mensaje

Nombre del tema: $iothub/telemetry

Propiedades:

Nombre Type Obligatorio Descripción
Tipo de contenido string no Se convierte en la propiedad del sistema content-type en el mensaje publicado.
content-encoding string no Se convierte en la propiedad del sistema content-encoding en el mensaje publicado.
message-id string no Se convierte en la propiedad del sistema message-id en el mensaje publicado.
user-id string no Se convierte en la propiedad del sistema user-id en el mensaje publicado.
correlation-id string no Se convierte en la propiedad del sistema correlation-id en el mensaje publicado.
creation-time time no Se convierte en la propiedad iothub-creation-time-utc en el mensaje publicado.

Sugerencia

El formato de creation-time debe ser UTC sin información de zona horaria. Por ejemplo, 2021-04-21T11:30:16Z es válido y 2021-04-21T11:30:16-07:00 no lo es.

Carga útil: cualquier secuencia de bytes

Reconocimiento de acción correcta

El mensaje se publicó correctamente en el canal de telemetría.

Propiedades: ninguna

Carga útil: vacía

Reconocimientos alternativos

Código de motivo Estado Nombre Descripción
131 0100 Bad Request El mensaje de la operación tiene un formato incorrecto y no se puede procesar.
135 0101 No autorizado El cliente no tiene autorización para realizar la operación.
131 0102 No permitida La operación no está permitida.
131 0601 Error de servidor Error interno del servidor.
151 0501 Limitado La tasa de solicitudes es demasiado alta por SKU.
151 0502 Cuota superada Se superó la cuota diaria por SKU actual.
131 0602 Tiempo de espera Se agotó el tiempo de espera de la operación antes de que pudiera completarse.
131 0603 Servidor ocupado Servidor ocupado.

Ejemplo 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

Respuestas

Bad Request

El mensaje de la operación tiene un formato incorrecto y no se puede procesar.

Código del motivo: 131

Estado: 0100

Propiedades:

Nombre Type Obligatorio Descripción
reason string no Contiene información sobre los elementos específicamente no válidos en relación con el mensaje.

Carga útil: vacía

Conflicto

La operación está en conflicto con otra operación en curso.

Código del motivo: 131

Estado: 0103

Propiedades:

Nombre Type Obligatorio Descripción
trace-id string no Identificador de seguimiento de correlación con otros diagnósticos del error.
reason string no Contiene información sobre los elementos específicamente no válidos en relación con el mensaje.

Carga útil: vacía

No permitida

La operación no está permitida.

Código del motivo: 131

Estado: 0102

Propiedades:

Nombre Type Obligatorio Descripción
reason string no Contiene información sobre los elementos específicamente no válidos en relación con el mensaje.

Carga útil: vacía

No autorizado

El cliente no tiene autorización para realizar la operación.

Código del motivo: 135

Estado: 0101

Propiedades:

Nombre Type Obligatorio Descripción
trace-id string no Identificador de seguimiento de correlación con otros diagnósticos del error.

Carga útil: vacía

No encontrado

El recurso solicitado no existe.

Código del motivo: 131

Estado: 0504

Propiedades:

Nombre Type Obligatorio Descripción
reason string no Contiene información sobre los elementos específicamente no válidos en relación con el mensaje.

Carga útil: vacía

No modificado

El recurso no se modificó según la condición previa proporcionada.

Código del motivo: 0

Estado: 0001

Propiedades: ninguna

Carga útil: vacía

Error en la condición previa

No se cumplió la condición previa por lo que se ha cancelado la solicitud.

Código del motivo: 131

Estado: 0104

Propiedades: ninguna

Carga útil: vacía

Cuota superada

Se superó la cuota diaria por SKU actual.

Código del motivo: 151

Estado: 0502

Propiedades: ninguna

Carga útil: vacía

Recurso agotado

El recurso no tiene capacidad para completar la operación.

Código del motivo: 131

Estado: 0503

Propiedades:

Nombre Type Obligatorio Descripción
reason string no Contiene información sobre los elementos específicamente no válidos en relación con el mensaje.

Carga útil: vacía

Servidor ocupado

Servidor ocupado.

Código del motivo: 131

Estado: 0603

Propiedades:

Nombre Type Obligatorio Descripción
trace-id string no Identificador de seguimiento de correlación con otros diagnósticos del error.

Carga útil: vacía

Error de servidor

Error interno del servidor.

Código del motivo: 131

Estado: 0601

Propiedades:

Nombre Type Obligatorio Descripción
trace-id string no Identificador de seguimiento de correlación con otros diagnósticos del error.

Carga útil: vacía

Error de destino

El destino respondió pero la respuesta no era válida o tenía un formato incorrecto.

Código del motivo: 131

Estado: 06A2

Propiedades:

Nombre Type Obligatorio Descripción
reason string no Contiene información sobre los elementos específicamente no válidos en relación con el mensaje.

Carga útil: vacía

Tiempo de espera agotado del destino

Se agotó el tiempo de espera para que el destino completara la solicitud.

Código del motivo: 131

Estado: 06A1

Propiedades:

Nombre Type Obligatorio Descripción
trace-id string no Identificador de seguimiento de correlación con otros diagnósticos del error.
reason string no Contiene información sobre los elementos específicamente no válidos en relación con el mensaje.

Carga útil: vacía

Destino no disponible

No se puede acceder al destino para completar la solicitud.

Código del motivo: 131

Estado: 06A0

Propiedades: ninguna

Carga útil: vacía

Limitado

La tasa de solicitudes es demasiado alta por SKU.

Código del motivo: 151

Estado: 0501

Propiedades: ninguna

Carga útil: vacía

Tiempo de espera

Se agotó el tiempo de espera de la operación antes de que pudiera completarse.

Código del motivo: 131

Estado: 0602

Propiedades:

Nombre Type Obligatorio Descripción
trace-id string no Identificador de seguimiento de correlación con otros diagnósticos del error.

Carga útil: vacía