Uso de la API de REST para crear y administrar las aplicaciones de IoT Central

Artículo
03/10/2024

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 el objeto de icono, 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
}

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
        }
    ]
}

Share via

Uso de la API de REST para crear y administrar las aplicaciones de IoT Central

Lista de las aplicaciones

Creación de una aplicación de IoT Central

Modificación de una aplicación de IoT Central

Eliminación de una aplicación de IoT Central

Paneles

API de REST de paneles

Agregar un panel

Icono de Gráfico de líneas

Icono de markdown

Icono del último valor conocido

Obtención de un panel

Actualización de un panel

Eliminar un panel

Enumeración de paneles

Recursos adicionales