Uso de la API de REST para crear y administrar las aplicaciones de IoT Central
Puede usar la API de REST de plano de control para crear y administrar trabajos en las aplicaciones de IoT Central. También puede usar la API de REST para:
- Agregar una identidad administrada a su aplicación.
- Administrar paneles en la aplicación
Para usar esta API, necesita un token de portador para el recurso management.azure.com. Para obtener un token de portador, puede usar la CLI de Azure:
az account get-access-token --resource https://management.azure.com
Para obtener información sobre cómo administrar una aplicación de IoT Central mediante la interfaz de usuario de IoT Central, consulte Creación de una aplicación de IoT Central.
Lista de las aplicaciones
Para obtener una lista de las aplicaciones de IoT Central en una suscripción:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Para obtener una lista de las aplicaciones de IoT Central en un grupo de recursos:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Puede recuperar los detalles de una aplicación individual:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Creación de una aplicación de IoT Central
Para crear una aplicación de IoT Central con una identidad administrada asignada por el sistema:
PUT https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
La carga siguiente muestra la configuración de la nueva aplicación, incluida la identidad administrada:
{
"location": "eastus",
"sku": {
"name": "ST2"
},
"properties": {
"displayName": "Contoso IoT Central App",
"subdomain": "my-iot-central-app",
"template": "iotc-pnp-preview@1.0.0"
},
"identity": {
"type": "SystemAssigned"
}
}
Modificación de una aplicación de IoT Central
Puede modificar una aplicación de IoT Central existente. En el ejemplo siguiente se muestra cómo cambiar el nombre para mostrar y habilitar la identidad administrada asignada por el sistema:
PATCH https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Use la carga siguiente para cambiar el nombre para mostrar y habilitar la identidad administrada asignada por el sistema:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Nota:
Solo puede agregar una identidad administrada a una aplicación de IoT Central que se creó en una región. Todas las aplicaciones nuevas se crean en una región.
Eliminación de una aplicación de IoT Central
Para eliminar una aplicación de IoT Central, use:
DELETE https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Paneles
Puede crear paneles asociados a una organización específica. Un panel de la organización solo es visible para los usuarios que tienen acceso a la organización a la que está asociado el panel. Solo los usuarios con un rol que tenga permisos de panel de la organización pueden crear, editar y eliminar paneles de la organización.
Todos los usuarios pueden crear paneles personales, visibles solo para ellos mismos. Los usuarios pueden cambiar entre los paneles de la organización y los personales.
Nota:
Actualmente no se admite la creación de paneles personales mediante la API.
Para aprender a administrar paneles mediante la interfaz de usuario de IoT Central, consulte Administración de paneles.
API de REST de paneles
La API de REST de IoT Central le permite:
- Adición de un panel a la aplicación
- Actualización de un panel en la aplicación
- Obtención de una lista del panel en la aplicación
- Obtención de un panel por identificador
- Eliminación de un panel en la aplicación
Agregar un panel
Use la siguiente solicitud para crear un panel.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId: un identificador DTMI único para el panel.
El cuerpo de la solicitud tiene algunos campos obligatorios:
@displayName: nombre para mostrar del panel.@favorite: ¿Está el panel en la lista de favoritos?group: id. de grupo de dispositivos.Tile: configuración que especifica un objeto de mosaico, incluido el diseño, el nombre para mostrar y la configuración.
Un icono tiene varios campos obligatorios:
| Nombre | Descripción |
|---|---|
displayName |
Nombre para mostrar del icono |
height |
Alto del icono |
width |
Ancho del icono |
x |
Posición horizontal del icono |
y |
Posición vertical del icono |
Las dimensiones y la ubicación de un icono usan unidades enteras. El icono más pequeño posible tiene un alto y ancho de uno.
Puede configurar un objeto de icono para mostrar varios tipos de datos. En este artículo se incluyen ejemplos de iconos que muestran gráficos de líneas, markdown y el último valor conocido. Para más información sobre los diferentes tipos de icono que puede agregar a un panel, consulte Tipos de icono.
Icono de Gráfico de líneas
Representan uno o varios valores de telemetría agregados para uno o más dispositivos durante un período de tiempo. Por ejemplo, puede mostrar un gráfico de líneas que trace la temperatura y presión medias de uno o varios dispositivos durante la última hora.
El icono del gráfico de líneas tiene la siguiente configuración:
| Nombre | Descripción |
|---|---|
capabilities |
Especifica el valor agregado de la telemetría que se va a mostrar. |
devices |
Lista de dispositivos que se van a mostrar. |
format |
Configuración de formato del gráfico, como los ejes que se van a usar. |
group |
Identificador del grupo de dispositivos que se va a mostrar. |
queryRange |
Intervalo de tiempo y resolución que se va a mostrar. |
type |
lineChart |
Icono de markdown
Iconos interactivos con un título y texto de descripción con formato de Markdown. La dirección URL puede ser un vínculo relativo a otra página de la aplicación, o bien un vínculo absoluto a un sitio externo. El icono de markdown tiene la siguiente configuración:
| Nombre | Descripción |
|---|---|
description |
Cadena markdown que se va a representar dentro del icono. |
href |
Vínculo que se va a visitar cuando se selecciona el icono. |
image |
Imagen codificada en base64 que se va a mostrar. |
type |
markdown |
Icono del último valor conocido
Muestran los valores de telemetría más recientes de uno o más dispositivos. Por ejemplo, puede usar este icono para mostrar los valores más recientes de temperatura, presión y humedad de uno o varios dispositivos.
El último icono de valor conocido (LKV) tiene la siguiente configuración:
| Nombre | Descripción |
|---|---|
capabilities |
Especifica la telemetría que se va a mostrar. |
devices |
Lista de dispositivos que se van a mostrar. |
format |
Configuración de formato del icono de LKV, como el tamaño de texto del ajuste de palabras. |
group |
Identificador del grupo de dispositivos que se va a mostrar. |
showTrend |
Muestra la diferencia entre el último valor conocido y el valor anterior. |
type |
lkv |
En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega un nuevo panel con iconos de gráfico de líneas, markdown y último valor conocido. Los iconos de gráfico de líneas y LKV son iconos de 2x2. El icono de markdown es un icono 1x1. Los iconos se organizan en la fila superior del panel:
{
"displayName": "My Dashboard ",
"tiles": [
{
"displayName": "LKV Temperature",
"configuration": {
"type": "lkv",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"format": {
"abbreviateValue": false,
"wordWrap": false,
"textSize": 14
}
},
"x": 0,
"y": 0,
"width": 2,
"height": 2
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Average temperature",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 3,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Agregar una configuración de la cuenta de almacenamiento de carga de archivos
Use la solicitud siguiente para crear una configuración de la cuenta de almacenamiento de blobs de carga de archivos en la aplicación de IoT Central:
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
El cuerpo de la solicitud tiene los campos siguientes:
account: nombre de la cuenta de almacenamiento donde se va a cargar el archivo.connectionString: cadena de conexión para conectarse a la cuenta de almacenamiento.container: nombre del contenedor dentro de la cuenta de almacenamiento. En el ejemplo siguiente se usa el nombrefileuploads.etag: etiqueta de entidad para evitar conflictos con varias cargassasTtl: estándar de duración ISO 8601, la cantidad de tiempo que la solicitud del dispositivo para cargar un archivo es válida antes de que expire.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H",
"state": "pending",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Obtener la configuración de la cuenta de almacenamiento de carga de archivos
Use la solicitud siguiente para recuperar detalles de una configuración de la cuenta de almacenamiento de blobs de carga de archivos en la aplicación de IoT Central:
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Actualización de la configuración de la cuenta de almacenamiento de carga de archivos
Use la siguiente solicitud para actualizar una cadena de conexión de la cuenta de almacenamiento de blobs de carga de archivos en la aplicación de IoT Central:
PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
{
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"sasTtl": "PT1H",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Eliminación de la configuración de la cuenta de almacenamiento de carga de archivos
Use la solicitud siguiente para eliminar una configuración de cuenta de almacenamiento:
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Obtención de un panel
Use la siguiente solicitud para recuperar los detalles de un panel mediante un identificador de panel.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Actualización de un panel
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
En el ejemplo siguiente se muestra un cuerpo de solicitud que actualiza el nombre para mostrar de un panel y agrega el panel a la lista de favoritos:
{
"displayName": "New Dashboard Name",
"favorite": true
}
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "New Dashboard Name",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 5,
"height": 5
}
],
"favorite": true
}
Eliminar un panel
Use la siguiente solicitud para eliminar un panel mediante el identificador del panel:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Enumeración de paneles
Use la siguiente solicitud para recuperar una lista de paneles de la aplicación:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
La respuesta a esta solicitud es similar al ejemplo siguiente:
{
"value": [
{
"id": "dtmi:kkfvwa2xi:p7pyt5x3o",
"displayName": "Dashboard",
"personal": false,
"tiles": [
{
"displayName": "Device templates",
"configuration": {
"type": "markdown",
"description": "Get started by adding your first device.",
"href": "/device-templates/new/devicetemplates",
"image": "f5ba1b00-1d24-4781-869b-6f954df48736"
},
"x": 1,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Quick start demo",
"configuration": {
"type": "markdown",
"description": "Learn how to use Azure IoT Central in minutes.",
"href": "https://aka.ms/iotcentral-pnp-video",
"image": "9eb01d71-491a-44e5-8fac-7af3bc9f9acd"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Tutorials",
"configuration": {
"type": "markdown",
"description": "Step-by-step articles teach you how to create apps and devices.",
"href": "https://aka.ms/iotcentral-pnp-tutorials",
"image": "7d9fc12c-d46e-41c6-885f-0a67c619366e"
},
"x": 3,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 4,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "IoT Central Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": ""
},
"x": 0,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Contoso Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": "c9ac5af4-f38e-4cd3-886a-e0cb107f391c"
},
"x": 0,
"y": 1,
"width": 5,
"height": 3
},
{
"displayName": "Available Memory",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
]
}