Compartir a través de

Uso de la API REST de IoT Central para administrar las exportaciones de datos

  • Artículo

La API de REST de IoT Central permite desarrollar aplicaciones cliente que se integran con aplicaciones de IoT Central. Puede usar la API REST para crear y administrar las exportaciones de datos en la aplicación de IoT Central.

Cada llamada a la API REST de IoT Central requiere un encabezado de autorización. Para obtener más información, vea los procedimientos de autenticación y autorización de llamadas a la API REST de IoT Central.

Para ver la documentación de referencia sobre la API REST de IoT Central, consulte Referencia de la API REST de Azure IoT Central.

Para aprender a administrar la exportación de datos mediante la interfaz de usuario de IoT Central, consulte Exportación de datos de IoT a Blob Storage.

Exportación de datos

Puede usar la característica de exportación de datos de IoT Central para transmitir datos de telemetría, cambios de propiedad, eventos de conectividad de dispositivos, eventos de ciclo de vida de dispositivos y eventos de ciclo de vida de plantilla de dispositivo a destinos como Azure Event Hubs, Azure Service Bus, Azure Blob Storage y puntos de conexión de webhook.

Cada definición de exportación de datos puede enviar datos a uno o varios destinos. Cree las definiciones de destino antes de crear la definición de exportación.

Creación o actualización de un destino

Use la siguiente solicitud para crear o actualizar una definición de destino:

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId es un id. exclusivo para el destino.

En el ejemplo siguiente se muestra un cuerpo de solicitud que crea un destino de almacenamiento de blob:

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    }
}

El cuerpo de la solicitud tiene algunos campos obligatorios:

  • displayName: nombre para mostrar del destino.
  • type: tipo del objeto de destino. Uno de los siguientes: blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@v1, servicebustopic@v1, webhook@v1.
  • authorization: los detalles de autorización del destino. Los tipos de autorización admitidos son systemAssignedManagedIdentity y connectionString.

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Obtener un destino por identificador

Use la siguiente solicitud para recuperar los detalles de un destino desde la aplicación:

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Destinos de la lista

Use la siguiente solicitud para recuperar una lista de destinos de la aplicación:

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
              "type": "systemAssignedManagedIdentity",
              "endpointUri": "https://yourapplication.blob.core.windows.net/",
              "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

Revisión de un destino

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Puede usar esta llamada para realizar una actualización incremental de una exportación. El cuerpo de la solicitud de ejemplo es similar al ejemplo siguiente, que actualiza containerName de un destino:

{
  "containerName": "central-data-analysis"
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data-analysis"
    },
    "status": "waiting"
}

Eliminar un destino

Use la siguiente solicitud para eliminar un destino:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Creación o actualización de una definición de exportación

Use la siguiente solicitud para crear o actualizar una definición de exportación de datos:

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

En el ejemplo siguiente se muestra un cuerpo de solicitud que crea una definición de exportación para la telemetría del dispositivo:

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

El cuerpo de la solicitud tiene algunos campos obligatorios:

  • displayName: nombre para mostrar de la exportación.
  • enabled: alterna para iniciar o detener la exportación de un envío de datos.
  • source: tipo de datos para exportar.
  • destinations: lista de destinos a los que la exportación debe enviar datos. Los identificadores de destino ya deben existir en la aplicación.

Hay algunos campos opcionales que puede usar para agregar más detalles a la exportación.

  • enrichments: fragmentos de información extra que se incluirán con cada mensaje enviado. Los datos se representan como un conjunto de pares clave/valor, donde la clave es el nombre del enriquecimiento que aparece en el mensaje de salida y el valor identifica los datos que se van a enviar.
  • filter: consulta que define qué eventos del origen se deben exportar.

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

Enriquecimientos

Hay tres tipos de enriquecimiento que se pueden agregar a una exportación: cadenas personalizadas, propiedades del sistema y propiedades personalizadas:

En el ejemplo siguiente se muestra cómo usar el nodo enrichments para agregar una cadena personalizada al mensaje saliente:

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

En el ejemplo siguiente se muestra cómo usar el nodo enrichments para agregar una propiedad del sistema al mensaje saliente:

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

Puede agregar las siguientes propiedades del sistema:

Propiedad Descripción
$enabled ¿Está habilitado el dispositivo?
$displayName El nombre de dispositivo.
$templateDisplayName Nombre de la plantilla de dispositivo.
$organizations Las organizaciones a las que pertenece el dispositivo.
$provisioned ¿Se aprovisiona el dispositivo?
$simulated ¿El dispositivo está simulado?

En el ejemplo siguiente se muestra cómo usar el nodo enrichments para agregar una propiedad personalizada al mensaje saliente. Las propiedades personalizadas son propiedades definidas en la plantilla de dispositivo a la que está asociado el dispositivo:

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

Filters

Puede filtrar los mensajes exportados en función de los valores de telemetría o propiedad.

En el ejemplo siguiente se muestra cómo usar el campo filter para exportar solo mensajes en los que el valor de telemetría accelerometer-X es mayor que 0:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

En el ejemplo siguiente se muestra cómo usar el campo filter para exportar solo mensajes en los que el valor de telemetría temperature es mayor que la propiedad targetTemperature:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

Obtener una exportación por identificador

Use la siguiente solicitud para recuperar los detalles de una definición de exportación desde la aplicación:

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "enrichments": {
    "Custom data": {
      "value": "My value"
    }
  },
  "destinations": [
    {
      "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
    }
  ],
  "status": "healthy"
}

Lista de definiciones de exportación

Use la siguiente solicitud para recuperar una lista de definiciones de exportación de la aplicación:

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

Revisión de una definición de exportación

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Puede usar esta llamada para realizar una actualización incremental de una exportación. El cuerpo de la solicitud de ejemplo es similar al ejemplo siguiente, que actualiza enrichments a una exportación:

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

Eliminar una definición de exportación

Use la siguiente solicitud para eliminar una definición de exportación:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Pasos siguientes

Ahora que ha aprendido a administrar la exportación de datos con la API de REST, el siguiente paso que se sugiere es Empleo de la API de REST de IoT Central para administrar plantillas de dispositivos.