Partekatu honen bidez:

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

  • Artikulua

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 nombre fileuploads.
  • etag: etiqueta de entidad para evitar conflictos con varias cargas
  • sasTtl: 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
        }
    ]
}