Použití rozhraní REST API k vytváření a správě aplikací IoT Central

Článek
06/24/2024

K vytváření a správě aplikací IoT Central můžete použít rozhraní REST API řídicí roviny. Rozhraní REST API můžete použít také k:

Přidejte do aplikace spravovanou identitu.
Správa řídicích panelů v aplikaci

K použití tohoto rozhraní API potřebujete nosný token prostředku management.azure.com . K získání nosné tokeny můžete použít Azure CLI:

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

Informace o správě aplikace IoT Central pomocí uživatelského rozhraní IoT Central najdete v tématu Vytvoření aplikace IoT Central.

Výpis aplikací

Získání seznamu aplikací IoT Central v předplatném:

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

Získání seznamu aplikací IoT Central ve skupině prostředků:

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

Můžete načíst podrobnosti o jednotlivých aplikacích:

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

Vytvoření aplikace IoT Central

Vytvoření aplikace IoT Central se spravovanou identitou přiřazenou systémem:

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

Následující datová část ukazuje konfiguraci nové aplikace, včetně spravované identity:

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

Úprava aplikace IoT Central

Existující aplikaci IoT Central můžete upravit. Následující příklad ukazuje, jak změnit zobrazovaný název a povolit spravovanou identitu přiřazenou systémem:

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

Pomocí následující datové části změňte zobrazovaný název a povolte spravovanou identitu přiřazenou systémem:

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

Poznámka:

Spravovanou identitu můžete přidat jenom do aplikace IoT Central, která byla vytvořena v oblasti. Všechny nové aplikace se vytvoří v oblasti.

Odstranění aplikace IoT Central

Pokud chcete odstranit aplikaci IoT Central, použijte:

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

Řídicí panely

Můžete vytvořit řídicí panely, které jsou přidružené ke konkrétní organizaci. Řídicí panel organizace je viditelný jenom uživatelům, kteří mají přístup k organizaci, ke které je řídicí panel přidružený. Řídicí panely organizace můžou vytvářet, upravovat a odstraňovat jenom uživatelé v roli, která má oprávnění řídicího panelu organizace.

Všichni uživatelé můžou vytvářet osobní řídicí panely, viditelné jenom pro sebe. Uživatelé můžou přepínat mezi organizačními a osobními řídicími panely.

Poznámka:

Vytváření osobních řídicích panelů pomocí rozhraní API se v současné době nepodporuje.

Informace o správě řídicích panelů pomocí uživatelského rozhraní IoT Central najdete v tématu Správa řídicích panelů.

Rozhraní REST API řídicích panelů

Rozhraní IoT Central REST API umožňuje:

Přidání řídicího panelu do aplikace
Aktualizace řídicího panelu v aplikaci
Získání seznamu řídicího panelu v aplikaci
Získání řídicího panelu podle ID
Odstranění řídicího panelu v aplikaci

Přidání řídicího panelu

K vytvoření řídicího panelu použijte následující požadavek.

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

dashboardId – Jedinečný identifikátor DTMI pro řídicí panel.

Text požadavku obsahuje některá povinná pole:

@displayName: Zobrazovaný název řídicího panelu.
@favorite: Je řídicí panel v seznamu oblíbených položek?
group: ID skupiny zařízení.
Tile : Konfigurace určující objekt dlaždice, včetně rozložení, zobrazovaného názvu a konfigurace.

Dlaždice obsahuje některá povinná pole:

Název	Popis
`displayName`	Zobrazovaný název dlaždice
`height`	Výška dlaždice
`width`	Šířka dlaždice
`x`	Vodorovné umístění dlaždice
`y`	Svislé umístění dlaždice

Dimenze a umístění dlaždice používají celočíselné jednotky. Nejmenší možná dlaždice má výšku a šířku jedné.

Objekt dlaždice můžete nakonfigurovat tak, aby zobrazoval více typů dat. Tento článek obsahuje příklady dlaždic, které zobrazují spojnicové grafy, markdown a poslední známou hodnotu. Další informace o různých typech dlaždic, které můžete přidat na řídicí panel, najdete v tématu Typy dlaždic.

Dlaždice spojnicového grafu

Vykreslte jednu nebo více agregovaných telemetrických hodnot pro jedno nebo více zařízení za časové období. Můžete například zobrazit spojnicový graf pro vykreslení průměrné teploty a tlaku jednoho nebo více zařízení za poslední hodinu.

Dlaždice spojnicového grafu má následující konfiguraci:

Název	Popis
`capabilities`	Určuje agregovanou hodnotu telemetrie, která se má zobrazit.
`devices`	Seznam zařízení, která se mají zobrazit.
`format`	Konfigurace formátu grafu, jako jsou osy, které se mají použít.
`group`	ID skupiny zařízení, které se má zobrazit.
`queryRange`	Časový rozsah a rozlišení, které se mají zobrazit.
`type`	`lineChart`

Dlaždice Markdown

Kliknutelné dlaždice, které zobrazují text nadpisu a popisu formátovaný v Markdownu. Adresa URL může být relativní odkaz na jinou stránku v aplikaci nebo absolutní odkaz na externí web. Dlaždice Markdown má následující konfiguraci:

Název	Popis
`description`	Řetězec markdownu, který se má vykreslit uvnitř dlaždice.
`href`	Odkaz, který chcete navštívit, když je vybraná dlaždice.
`image`	Zobrazí se obrázek s kódováním Base64.
`type`	`markdown`

Dlaždice poslední známé hodnoty

Zobrazí nejnovější hodnoty telemetrie pro jedno nebo více zařízení. Tuto dlaždici můžete například použít k zobrazení nejnovějších hodnot teploty, tlaku a vlhkosti pro jedno nebo více zařízení.

Dlaždice poslední známé hodnoty (LKV) má následující konfiguraci:

Název	Popis
`capabilities`	Určuje telemetrii, která se má zobrazit.
`devices`	Seznam zařízení, která se mají zobrazit.
`format`	Konfigurace formátu dlaždice LKV, například velikost textu obtékání textu.
`group`	ID skupiny zařízení, které se má zobrazit.
`showTrend`	Zobrazí rozdíl mezi poslední známou hodnotou a předchozí hodnotou.
`type`	`lkv`

Následující příklad ukazuje text požadavku, který přidá nový řídicí panel s spojnicovým grafem, markdownem a dlaždicemi s poslední známou hodnotou. Dlaždice LKV a spojnicového grafu jsou 2x2 dlaždice. Dlaždice Markdownu 1x1 je dlaždice. Dlaždice jsou uspořádány na horním řádku řídicího panelu:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Přidání konfigurace účtu úložiště pro nahrání souboru

Pomocí následujícího požadavku vytvořte v aplikaci IoT Central konfiguraci účtu úložiště objektů blob pro nahrání souboru:

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

Text požadavku má následující pole:

account: Název účtu úložiště, do kterého chcete soubor nahrát.
connectionString: Připojovací řetězec pro připojení k účtu úložiště.
container: Název kontejneru uvnitř účtu úložiště. Následující příklad používá název fileuploads.
etag: ETag, aby se zabránilo konfliktu s více nahráváními
sasTtl: Standard doby trvání ISO 8601, doba, po kterou je požadavek zařízení na nahrání souboru platný před vypršením jeho platnosti.

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

}

Získání konfigurace účtu úložiště pro nahrání souboru

Pomocí následujícího požadavku načtěte podrobnosti o konfiguraci účtu úložiště objektů blob nahrání souboru v aplikaci IoT Central:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

}

Aktualizace konfigurace účtu úložiště pro nahrání souboru

Pomocí následujícího požadavku aktualizujte účet úložiště objektů blob pro nahrání souboru připojovací řetězec ve vaší aplikaci 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/"
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:


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

Odebrání konfigurace účtu úložiště pro nahrání souboru

K odstranění konfigurace účtu úložiště použijte následující požadavek:

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

Získání řídicího panelu

Pomocí následujícího požadavku načtěte podrobnosti řídicího panelu pomocí ID řídicího panelu.

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Aktualizace řídicího panelu

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

Následující příklad ukazuje text požadavku, který aktualizuje zobrazovaný název řídicího panelu a přidá řídicí panel do seznamu oblíbených položek:


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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranění řídicího panelu

Pomocí následujícího požadavku odstraňte řídicí panel pomocí ID řídicího panelu:

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

Výpis řídicích panelů

Pomocí následujícího požadavku načtěte seznam řídicích panelů z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Sdílet prostřednictvím

Použití rozhraní REST API k vytváření a správě aplikací IoT Central

Výpis aplikací

Vytvoření aplikace IoT Central

Úprava aplikace IoT Central

Odstranění aplikace IoT Central

Řídicí panely

Rozhraní REST API řídicích panelů

Přidání řídicího panelu

Dlaždice spojnicového grafu

Dlaždice Markdown

Dlaždice poslední známé hodnoty

Přidání konfigurace účtu úložiště pro nahrání souboru

Získání konfigurace účtu úložiště pro nahrání souboru

Aktualizace konfigurace účtu úložiště pro nahrání souboru

Odebrání konfigurace účtu úložiště pro nahrání souboru

Získání řídicího panelu

Aktualizace řídicího panelu

Odstranění řídicího panelu

Výpis řídicích panelů

Váš názor

Další materiály