REST de IoT Hub

  • Artículo
  • Tiempo de lectura: 3 minutos

Las API REST para IoT Hub ofrecen acceso mediante programación a los servicios de dispositivo, mensajería y trabajo, así como al proveedor de recursos, en IoT Hub. Puede acceder a servicios de mensajería desde un servicio de IoT que se ejecute en Azure o directamente en Internet desde cualquier aplicación que pueda enviar una solicitud HTTP y recibir una respuesta HTTP.

Servicio

  • Use esta API para administrar IoT Hub dispositivos gemelos. Puede recuperar y actualizar las propiedades del dispositivo gemelo e invocar métodos directos en los dispositivos.
  • Use estas API para administrar identidades de dispositivo en el registro de identidades de un centro de IoT.
  • Use estas API para administrar trabajos en IoT Hub. Puede programar, cancelar u obtener un trabajo.

Todas las operaciones de tarea se ajustan a la especificación del protocolo HTTP/1.1 y cada operación devuelve un encabezado que se puede usar para obtener x-ms-request-id información sobre la solicitud. Debe asegurarse de que las solicitudes realizadas a estos recursos sean seguras. Para obtener más información, consulte IoT Hub Developer Guide – Security for the specifics on how to create security tokens (Guía para desarrolladores: seguridad para obtener información específica sobre cómo crear tokens de seguridad).

Mensajería de dispositivos

Use estas API desde un dispositivo para enviar mensajes del dispositivo a la nube a un centro de IoT y recibir mensajes de nube a dispositivo desde un centro de IoT. Todas las operaciones de tarea cumplen la especificación del protocolo HTTP/1.1. Debe asegurarse de que las solicitudes realizadas a estos recursos sean seguras. Para obtener más información, consulte IoT Hub Developer Guide - Security (Guía para desarrolladores de aplicaciones: seguridad) para obtener información específica sobre cómo crear tokens de seguridad.

Proveedor de recursos

Use estas API para administrar la implementación de los IoT Hub recursos. Para obtener información sobre cómo proteger estas solicitudes, consulte Referencia de la API REST de Azure.

Parámetros y encabezados comunes

La siguiente información es común a todas las tareas relacionadas con IoT Hub:

  • Reemplace {api-version} por "2018-06-30" en el URI.

  • Reemplace {subscription-id} por su identificador de suscripción en el URI.

  • Reemplace {resourceGroupName} por el nombre del grupo de recursos que contiene (o contendrá) el centro de IoT.

  • Reemplace {IoTHubName} por el nombre del centro de IoT.

  • Establezca el encabezado Content-Type en application/json.

  • Establezca el encabezado Autorización en un token de SAS creado como se especifica en la sección tokens de seguridad de Uso de IoT Hub tokens de seguridad.

  • El encabezado Etag se devuelve en todas las solicitudes con ámbito en una única identidad de dispositivo, según RFC7232.

  • Todas las operaciones PUT/PATCH requieren que se especifiquen los encabezados siguientes: If-Match = [*|<etag from get>]

  • Las operaciones DELETE pueden incluir el encabezado siguiente: If-Match = [*|<etag from get>]

El comportamiento de las etiquetas ETag se puede ver a continuación:
PUT El recurso no existe El recurso existe
If-Match = "" / absent 201 Creado 200 OK
If-Match = "*" 412 Error de condición previa 200 OK
If-Match = "xyz" 412 Error de condición previa 200 OK /412 Precondition Failed
If-None-Match = "*" 201 Creado 412 Error de condición previa
Delete El recurso no existe El recurso existe
If-Match = "" / absent 204 No Content 200 OK
If-Match = "*" 204 No Content 200 OK
If-Match = "xyz" 204 No Content 200 OK /412 Precondition Failed

Para llamadas asincrónicas:

  • PUT responde con 201 Creado con Azure-AsyncOperation encabezado para cualquier operación asincrónica. Todas las operaciones sincrónicas (actualizaciones) devuelven 200 OK.

  • DELETE devuelve 202 Accepted con los encabezados Location Retry-After y Azure-AsyncOperation encabezado para los recursos que existen.

  • El encabezado location contiene la dirección URL del resultado de la operación.

  • Retry-After encabezado contiene el intervalo de reintento adecuado en segundos

  • Azure-AsyncOperation encabezado contiene la dirección URL del estado del resultado de la operación asincrónica

  • Al finalizar, get a la dirección URL del resultado de la operación genera exactamente el mismo resultado que si la operación original se hubiera completado sincrónicamente.