Condividi tramite


Usare l'API REST per creare e gestire applicazioni IoT Central

È possibile usare l'API REST del piano di controllo per creare e gestire applicazioni IoT Central. Inoltre, è possibile usare l'API REST per:

  • Aggiungere un'identità gestita all'applicazione.
  • Gestire i dashboard nell'applicazione

Per usare questa API, è necessario un token di connessione per la risorsa management.azure.com. Per ottenere un token di connessione, è possibile usare l'interfaccia della riga di comando di Azure:

az account get-access-token --resource https://management.azure.com

Per informazioni su come gestire l'applicazione IoT Central tramite l'interfaccia utente di IoT Central, vedere Creare un'applicazione IoT Central.

Elencare le applicazioni

Per ottenere un elenco delle applicazioni IoT Central in una sottoscrizione:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01

Per ottenere un elenco delle applicazioni IoT Central in un gruppo di risorse:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01

È possibile recuperare i dettagli di una singola applicazione:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01

Creazione di un'applicazione IoT Central

Per creare un'applicazione IoT Central con un'identità gestita assegnata dal 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

Il payload seguente illustra la configurazione per la nuova applicazione, inclusa l'identità gestita:

{
  "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"
  }
}

Modificare un'applicazione IoT Central

È possibile modificare un'applicazione IoT Central esistente. L'esempio seguente illustra come modificare il nome visualizzato e abilitare l'identità gestita assegnata dal 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

Usare il payload seguente per modificare il nome visualizzato e abilitare l'identità gestita assegnata dal sistema:

{
  "properties": {
    "displayName": "Contoso IoT Central App"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Nota

È possibile aggiungere un'identità gestita solo a un'applicazione IoT Central creata in un'area. Tutte le nuove applicazioni vengono create in un'area.

Eliminare un'applicazione IoT Central

Per eliminare un'applicazione IoT Central, usare:

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

Dashboard

È possibile creare dashboard associati a un'organizzazione specifica. Il dashboard di un'organizzazione è visibile solo agli utenti che hanno accesso all'organizzazione a cui è associato il dashboard. Solo gli utenti di un ruolo che dispone delle autorizzazioni per i dashboard dell'organizzazione possono crearli, modificarli ed eliminarli.

Tutti gli utenti possono creare dashboard personali, visibili solo a se stessi. Gli utenti possono passare dai dashboard dell'organizzazione ai dashboard personali e viceversa.

Nota

La creazione di dashboard personali tramite API non è attualmente supportata.

Per informazioni su come gestire i dashboard usando l'interfaccia utente di IoT Central, vedere Come gestire i dashboard.

API REST dei dashboard

L'API REST di IoT Central consente di:

  • Aggiungere un dashboard all'applicazione
  • Aggiornare un dashboard nell'applicazione
  • Ottenere un elenco del dashboard nell'applicazione
  • Ottenere un dashboard in base all'ID
  • Eliminare un dashboard nell'applicazione

Aggiungere un dashboard

Usare la richiesta seguente per creare un dashboard.

PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

dashboardId - Identificatore DTMI univoco per il dashboard.

Il corpo della richiesta include alcuni campi obbligatori:

  • @displayName: nome visualizzato del dashboard.
  • @favorite: il dashboard è presente nell'elenco dei preferiti?
  • group: ID del gruppo di dispositivi.
  • Tile : configurazione che specifica un oggetto riquadro, incluso il layout, il nome visualizzato e la configurazione.

Il riquadro include alcuni campi obbligatori:

Nome Descrizione
displayName Nome visualizzato del riquadro
height Altezza del riquadro
width Larghezza del riquadro
x Posizione orizzontale del riquadro
y Posizione verticale del riquadro

Le dimensioni e la posizione di un riquadro utilizzano entrambe unità intere. Il riquadro più piccolo possibile ha un'altezza e una larghezza pari a uno.

È possibile configurare un oggetto riquadro per visualizzare più tipi di dati. Questo articolo include esempi di riquadri che mostrano grafici a linee, markdown e l’ultimo valore noto. Per altre informazioni sui diversi tipi di riquadro che è possibile aggiungere a un dashboard, vedere Tipi di riquadro.

Riquadro Grafico a linee

Tracciare uno o più valori di telemetria aggregati per uno o più dispositivi in un periodo di tempo. Ad esempio, è possibile visualizzare un grafico a linee per tracciare la temperatura media e la pressione di uno o più dispositivi nell'ultima ora.

Il riquadro del grafico a linee presenta la configurazione seguente:

Nome Descrizione
capabilities Specifica il valore aggregato dei dati di telemetria da visualizzare.
devices Elenco dei dispositivi da visualizzare.
format Configurazione del formato del grafico, ad esempio gli assi da utilizzare.
group ID del gruppo di dispositivi da visualizzare.
queryRange Intervallo di tempo e risoluzione da visualizzare.
type lineChart

Riquadro Markdown

Riquadri selezionabili che visualizzano un'intestazione e un testo di descrizione formattati in Markdown. L'URL può essere un collegamento relativo a un'altra pagina nell'applicazione o un collegamento assoluto a un sito esterno. Il riquadro markdown presenta la configurazione seguente:

Nome Descrizione
description Stringa markdown di cui eseguire il rendering all'interno del riquadro.
href Collegamento da visitare quando viene selezionato il riquadro.
image Immagine con codifica Base64 da visualizzare.
type markdown

Riquadro dell’ultimo valore noto.

Visualizzare i valori di telemetria più recenti per uno o più dispositivi. È ad esempio possibile usare un riquadro di questo tipo per visualizzare i valori più recenti relativi a temperatura, pressione e umidità per uno o più dispositivi.

Il riquadro dell’ultimo valore noto (LKV) presenta la configurazione seguente:

Nome Descrizione
capabilities Specifica i dati di telemetria da visualizzare.
devices Elenco dei dispositivi da visualizzare.
format Configurazione del formato del riquadro LKV, ad esempio le dimensioni del testo del ritorno a capo automatico.
group ID del gruppo di dispositivi da visualizzare.
showTrend Mostrare la differenza tra l'ultimo valore noto e il valore precedente.
type lkv

Nell'esempio seguente viene illustrato un corpo della richiesta che aggiunge un nuovo dashboard con riquadri di grafico a linee, markdown e ultimo valore noto. I riquadri di LKV e del grafico a linee sono riquadri 2x2. Il riquadro markdown è un riquadro 1x1. I riquadri sono disposti nella riga superiore del dashboard:

{
    "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 risposta a questa richiesta è simile all'esempio seguente:

{
    "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
}

Aggiungere una configurazione dell'account di archiviazione per il caricamento di file

Usare la richiesta seguente per creare una configurazione dell'account di archiviazione BLOB per il caricamento di file nell'applicazione IoT Central:

PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

Il corpo della richiesta include i campi seguenti:

  • account: nome dell'account di archiviazione in cui caricare il file.
  • connectionString: stringa di connessione per la connessione all'account di archiviazione.
  • container: nome del contenitore all'interno dell'account di archiviazione. Nell'esempio seguente viene usato il nome fileuploads.
  • etag: ETag per evitare conflitti con caricamenti multipli
  • sasTtl: standard di durata ISO 8601, ovvero la quantità di tempo in cui la richiesta di caricamento di un file da parte del dispositivo è valida prima della scadenza.
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

La risposta a questa richiesta è simile all'esempio seguente:

{
  "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\""

}

Ottenere la configurazione dell'account di archiviazione per il caricamento di file

Usare la richiesta seguente per recuperare i dettagli di una configurazione dell'account di archiviazione BLOB per il caricamento di file nell'applicazione IoT Central:

GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

La risposta a questa richiesta è simile all'esempio seguente:

{
  "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\""

}

Aggiornare la configurazione dell'account di archiviazione per il caricamento di file

Usare la richiesta seguente per aggiornare una stringa di connessione dell'account di archiviazione BLOB per il caricamento di file nell'applicazione 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 risposta a questa richiesta è simile all'esempio seguente:


{
  "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\""
}

Rimuovere la configurazione dell'account di archiviazione per il caricamento di file

Usare la richiesta seguente per eliminare una configurazione dell'account di archiviazione:

DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

Ottenere un dashboard

Usare la richiesta seguente per recuperare i dettagli di un dashboard tramite un ID dashboard.

GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

La risposta a questa richiesta è simile all'esempio seguente:

{
    "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
}

Aggiornare un dashboard

PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

L'esempio seguente mostra un corpo della richiesta che aggiorna il nome visualizzato di un dashboard e aggiunge il dashboard all'elenco dei preferiti:


{
    "displayName": "New Dashboard Name",
    "favorite": true
}

La risposta a questa richiesta è simile all'esempio seguente:

{
    "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
}

Eliminare un dashboard

Usare la richiesta seguente per eliminare un dashboard tramite l'ID dashboard:

DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview

Elencare i dashboard

Usare la richiesta seguente per recuperare un elenco di dashboard dall'applicazione:

GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview

La risposta a questa richiesta è simile all'esempio seguente:

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