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 nomefileuploads.etag: ETag per evitare conflitti con caricamenti multiplisasTtl: 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
}
]
}
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per