Läs på engelska

Dela via

Använda REST API för att skapa och hantera IoT Central-program

  • Artikel

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

Anteckning

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.

Anteckning

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

Lägga till en lagringskontokonfiguration för filuppladdning

Använd följande begäran för att skapa en konfiguration av bloblagringskontot för filuppladdning i ditt IoT Central-program:

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

Begärandetexten har följande fält:

  • account: Namnet på lagringskontot där filen ska laddas upp till.
  • connectionString: Anslutningssträng för att ansluta till lagringskontot.
  • container: Namnet på containern i lagringskontot. I följande exempel används namnet fileuploads.
  • etag: ETag för att förhindra konflikt med flera uppladdningar
  • sasTtl: ISO 8601 duration standard, Den tid som enhetens begäran om att ladda upp en fil är giltig innan den upphör att gälla.
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

Svaret på den här begäran ser ut som i följande exempel:

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

}

Hämta konfigurationen av lagringskontot för filuppladdning

Använd följande begäran för att hämta information om en konfiguration av ett bloblagringskonto för filuppladdning i ditt IoT Central-program:

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

Svaret på den här begäran ser ut som i följande exempel:

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

}

Uppdatera konfigurationen av lagringskontot för filuppladdning

Använd följande begäran för att uppdatera ett bloblagringskonto för filuppladdning anslutningssträng i ditt IoT Central-program:

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

Svaret på den här begäran ser ut som i följande exempel:


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

Ta bort konfigurationen av lagringskontot för filuppladdning

Använd följande begäran för att ta bort en konfiguration av lagringskontot:

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

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