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

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