Använda REST API för att skapa och hantera IoT Central-program
Du kan använda rest-API:et för kontrollplanet för att skapa och hantera IoT Central-program. Du kan också använda REST-API:et för att:
- Lägg till en hanterad identitet i ditt program.
- Hantera instrumentpaneler i ditt program
Om du vill använda det här API:et behöver du en ägartoken för resursen management.azure.com . Om du vill hämta en ägartoken kan du använda Azure CLI:
az account get-access-token --resource https://management.azure.com
Mer information om hur du hanterar IoT Central-program med hjälp av IoT Central-användargränssnittet finns i Skapa ett IoT Central-program.
Visa en lista över dina program
Så här hämtar du en lista över IoT Central-programmen i en prenumeration:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Så här hämtar du en lista över IoT Central-programmen i en resursgrupp:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Du kan hämta information om ett enskilt program:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Skapa ett IoT Central-program
Så här skapar du ett IoT Central-program med en systemtilldelad hanterad identitet:
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
Följande nyttolast visar konfigurationen för det nya programmet, inklusive den hanterade identiteten:
{
"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"
}
}
Ändra ett IoT Central-program
Du kan ändra ett befintligt IoT Central-program. I följande exempel visas hur du ändrar visningsnamnet och aktiverar den systemtilldelade hanterade identiteten:
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
Använd följande nyttolast för att ändra visningsnamnet och aktivera den systemtilldelade hanterade identiteten:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Kommentar
Du kan bara lägga till en hanterad identitet i ett IoT Central-program som har skapats i en region. Alla nya program skapas i en region.
Ta bort ett IoT Central-program
Om du vill ta bort ett IoT Central-program använder du:
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
Instrumentpaneler
Du kan skapa instrumentpaneler som är associerade med en viss organisation. En organisationsinstrumentpanel är bara synlig för användare som har åtkomst till den organisation som instrumentpanelen är associerad med. Endast användare i en roll som har behörigheter för organisationsinstrumentpaneler kan skapa, redigera och ta bort organisationsinstrumentpaneler.
Alla användare kan skapa personliga instrumentpaneler, endast synliga för sig själva. Användare kan växla mellan organisationsinstrumentpaneler och personliga instrumentpaneler.
Kommentar
Det går för närvarande inte att skapa personliga instrumentpaneler med HJÄLP av API: et.
Mer information om hur du hanterar instrumentpaneler med hjälp av IoT Central-användargränssnittet finns i Hantera instrumentpaneler.
REST API för instrumentpaneler
I REST-API:et för IoT Central kan du göra följande:
- Lägga till en instrumentpanel i ditt program
- Uppdatera en instrumentpanel i ditt program
- Hämta en lista över instrumentpanelen i programmet
- Hämta en instrumentpanel efter ID
- Ta bort en instrumentpanel i ditt program
Lägg till instrumentpanel
Använd följande begäran för att skapa en instrumentpanel.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId – En unik DTMI-identifierare för instrumentpanelen.
Begärandetexten innehåller några obligatoriska fält:
@displayName: Instrumentpanelens visningsnamn.@favorite: Finns instrumentpanelen i listan favoriter?group: Enhetsgrupps-ID.Tile: Konfiguration som anger panelobjekt, inklusive layout, visningsnamn och konfiguration.
Panelen har några obligatoriska fält:
| Name | beskrivning |
|---|---|
displayName |
Visningsnamn för panelen |
height |
Panelens höjd |
width |
Panelens bredd |
x |
Panelens vågräta position |
y |
Panelens lodräta position |
Dimensionerna och platsen för en panel använder båda heltalsenheter. Den minsta möjliga panelen har en höjd och bredd på en.
Du kan konfigurera ett panelobjekt så att det visar flera typer av data. Den här artikeln innehåller exempel på paneler som visar linjediagram, markdown och senaste kända värde. Mer information om de olika paneltyper som du kan lägga till på en instrumentpanel finns i Paneltyper.
Linjediagramspanel
Rita upp ett eller flera aggregerade telemetrivärden för en eller flera enheter under en tidsperiod. Du kan till exempel visa ett linjediagram för att rita genomsnittstemperaturen och trycket för en eller flera enheter under den senaste timmen.
Linjediagrampanelen har följande konfiguration:
| Name | beskrivning |
|---|---|
capabilities |
Anger det aggregerade värdet för telemetrin som ska visas. |
devices |
Listan över enheter som ska visas. |
format |
Formatkonfigurationen för diagrammet, till exempel de axlar som ska användas. |
group |
ID:t för den enhetsgrupp som ska visas. |
queryRange |
Tidsintervall och upplösning som ska visas. |
type |
lineChart |
Markdown-panel
Klickbara paneler som visar en rubrik och en beskrivningstext formaterad i Markdown. URL:en kan vara en relativ länk till en annan sida i programmet eller en absolut länk till en extern webbplats. Markdown-panelen har följande konfiguration:
| Name | beskrivning |
|---|---|
description |
Markdown-strängen som ska återges i panelen. |
href |
Länken som ska besökas när panelen är markerad. |
image |
En base64-kodad bild som ska visas. |
type |
markdown |
Senast kända värdepanel
Visa de senaste telemetrivärdena för en eller flera enheter. Du kan till exempel använda den här panelen för att visa de senaste temperatur-, tryck- och luftfuktighetsvärdena för en eller flera enheter.
Panelen för det senast kända värdet (LKV) har följande konfiguration:
| Name | beskrivning |
|---|---|
capabilities |
Anger telemetrin som ska visas. |
devices |
Listan över enheter som ska visas. |
format |
Formatkonfigurationen för LKV-panelen, till exempel textstorlek för ordomslutning. |
group |
ID:t för den enhetsgrupp som ska visas. |
showTrend |
Visa skillnaden mellan det senast kända värdet och det tidigare värdet. |
type |
lkv |
I följande exempel visas en begärandetext som lägger till en ny instrumentpanel med linjediagram, markdown och senast kända värdepaneler. Panelerna LKV och linjediagram är 2x2 paneler. Markdown-panelen är en 1x1 panel. Panelerna är ordnade på den översta raden på instrumentpanelen:
{
"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
}
Svaret på den här begäran ser ut som i följande exempel:
{
"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
}
Hämta en instrumentpanel
Använd följande begäran för att hämta information om en instrumentpanel med hjälp av ett instrumentpanels-ID.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Svaret på den här begäran ser ut som i följande exempel:
{
"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
}
Uppdatera en instrumentpanel
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
I följande exempel visas en begärandetext som uppdaterar visningsnamnet för en instrumentpanel och lägger till instrumentpanelen i listan med favoriter:
{
"displayName": "New Dashboard Name",
"favorite": true
}
Svaret på den här begäran ser ut som i följande exempel:
{
"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
}
Ta bort en instrumentpanel
Använd följande begäran för att ta bort en instrumentpanel med hjälp av instrumentpanelens ID:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Lista instrumentpaneler
Använd följande begäran för att hämta en lista över instrumentpaneler från ditt program:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
Svaret på den här begäran ser ut som i följande exempel:
{
"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
}
]
}