Použití rozhraní REST API k vytváření a správě aplikací IoT Central
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ázevfileuploads.etag: ETag, aby se zabránilo konfliktu s více nahrávánímisasTtl: 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
}
]
}
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro