De REST API gebruiken om IoT Central-toepassingen te maken en te beheren
U kunt de REST API van het besturingsvlak gebruiken om IoT Central-toepassingen te maken en te beheren. U kunt ook de REST API gebruiken voor het volgende:
- Voeg een beheerde identiteit toe aan uw toepassing.
- Dashboards in uw toepassing beheren
Als u deze API wilt gebruiken, hebt u een Bearer-token nodig voor de management.azure.com resource. Als u een Bearer-token wilt ophalen, kunt u de Azure CLI gebruiken:
az account get-access-token --resource https://management.azure.com
Uw toepassingen vermelden
Een lijst met de IoT Central-toepassingen in een abonnement ophalen:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Een lijst met de IoT Central-toepassingen in een resourcegroep ophalen:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
U kunt de details van een afzonderlijke toepassing ophalen:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Een Azure IoT Central-toepassing maken
Een IoT Central-toepassing maken met een door het systeem toegewezen beheerde identiteit:
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
De volgende nettolading toont de configuratie voor de nieuwe toepassing, met inbegrip van de beheerde identiteit:
{
"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"
}
}
Een IoT Central-toepassing wijzigen
U kunt een bestaande IoT Central-toepassing wijzigen. In het volgende voorbeeld ziet u hoe u de weergavenaam wijzigt en de door het systeem toegewezen beheerde identiteit inschakelt:
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
Gebruik de volgende nettolading om de weergavenaam te wijzigen en de door het systeem toegewezen beheerde identiteit in te schakelen:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Notitie
U kunt alleen een beheerde identiteit toevoegen aan een IoT Central-toepassing die in een regio is gemaakt. Alle nieuwe toepassingen worden gemaakt in een regio.
Een IoT Central-toepassing verwijderen
Als u een IoT Central-toepassing wilt verwijderen, gebruikt u:
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
Dashboards
U kunt dashboards maken die zijn gekoppeld aan een specifieke organisatie. Een organisatiedashboard is alleen zichtbaar voor gebruikers die toegang hebben tot de organisatie waaraan het dashboard is gekoppeld. Alleen gebruikers met een rol met organisatiedashboardmachtigingen kunnen organisatiedashboards maken, bewerken en verwijderen.
Alle gebruikers kunnen persoonlijke dashboards maken, alleen zichtbaar voor zichzelf. Gebruikers kunnen schakelen tussen organisatie- en persoonlijke dashboards.
Notitie
Het maken van persoonlijke dashboards met behulp van API wordt momenteel niet ondersteund.
Dashboards REST API
Met behulp van de REST API van IoT Central kunt u:
- Een dashboard toevoegen aan uw toepassing
- Een dashboard in uw toepassing bijwerken
- Een lijst met het dashboard in de toepassing ophalen
- Een dashboard ophalen op id
- Een dashboard in uw toepassing verwijderen
Een dashboard toevoegen
Gebruik de volgende aanvraag om een dashboard te maken.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId - Een unieke DTMI-id voor het dashboard.
De hoofdtekst van de aanvraag bevat enkele vereiste velden:
@displayName: Weergavenaam van het dashboard.@favorite: Bevindt het dashboard zich in de lijst met favorieten?group: Apparaatgroep-id.Tile: Configuratie die een tegelobject opgeeft, inclusief de indeling, weergavenaam en configuratie.
Tegel bevat enkele vereiste velden:
| Name | Beschrijving |
|---|---|
displayName |
Weergavenaam van de tegel |
height |
Hoogte van de tegel |
width |
Breedte van de tegel |
x |
Horizontale positie van de tegel |
y |
Verticale positie van de tegel |
De dimensies en locatie van een tegel maken beide gebruik van gehele getallen. De kleinste mogelijke tegel heeft een hoogte en breedte van een tegel.
U kunt een tegelobject configureren om meerdere typen gegevens weer te geven. Dit artikel bevat voorbeelden van tegels met lijndiagrammen, markdown en laatst bekende waarde. Zie Tegeltypen voor meer informatie over de verschillende tegeltypen die u aan een dashboard kunt toevoegen.
Tegel Lijndiagram
Teken een of meer geaggregeerde telemetriewaarden voor een of meer apparaten gedurende een bepaalde periode. U kunt bijvoorbeeld een lijndiagram weergeven om de gemiddelde temperatuur en druk van een of meer apparaten in het afgelopen uur weer te geven.
De tegel lijndiagram heeft de volgende configuratie:
| Name | Beschrijving |
|---|---|
capabilities |
Hiermee geeft u de geaggregeerde waarde van de telemetrie weer te geven. |
devices |
De lijst met apparaten die moeten worden weergegeven. |
format |
De indelingsconfiguratie van de grafiek, zoals de assen die moeten worden gebruikt. |
group |
De id van de apparaatgroep die moet worden weergegeven. |
queryRange |
Het tijdsbereik en de resolutie die moet worden weergegeven. |
type |
lineChart |
Markdown-tegel
Klikbare tegels waarin een kop- en beschrijvingstekst wordt weergegeven die is opgemaakt in Markdown. De URL kan een relatieve koppeling naar een andere pagina in de toepassing zijn of een absolute koppeling naar een externe site. De markdown-tegel heeft de volgende configuratie:
| Name | Beschrijving |
|---|---|
description |
De Markdown-tekenreeks die in de tegel moet worden weergegeven. |
href |
De koppeling die u wilt bezoeken wanneer de tegel is geselecteerd. |
image |
Een base64-gecodeerde afbeelding die moet worden weergegeven. |
type |
markdown |
Laatst bekende waardetegel
De meest recente telemetriewaarden voor een of meer apparaten weergeven. U kunt deze tegel bijvoorbeeld gebruiken om de meest recente temperatuur-, druk- en vochtigheidswaarden voor een of meer apparaten weer te geven.
De tegel laatst bekende waarde (LKV) heeft de volgende configuratie:
| Name | Beschrijving |
|---|---|
capabilities |
Hiermee geeft u de telemetrie weer te geven. |
devices |
De lijst met apparaten die moeten worden weergegeven. |
format |
De indelingsconfiguratie van de LKV-tegel, zoals tekstgrootte van tekstterugloop. |
group |
De id van de apparaatgroep die moet worden weergegeven. |
showTrend |
Geef het verschil weer tussen de laatst bekende waarde en de vorige waarde. |
type |
lkv |
In het volgende voorbeeld ziet u een aanvraagbody waarmee een nieuw dashboard wordt toegevoegd met lijndiagram, Markdown en laatst bekende waardetegels. De LKV- en lijndiagramtegels zijn 2x2 tegels. De markdown-tegel is een 1x1 tegel. De tegels worden gerangschikt op de bovenste rij van het 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
}
Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:
{
"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
}
Een opslagaccountconfiguratie voor het uploaden van bestanden toevoegen
Gebruik de volgende aanvraag om een blob-opslagaccountconfiguratie voor het uploaden van bestanden te maken in uw IoT Central-toepassing:
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
De hoofdtekst van de aanvraag heeft de volgende velden:
account: de naam van het opslagaccount waarnaar het bestand moet worden geüpload.connectionString: de verbindingsreeks om verbinding te maken met het opslagaccount.container: De naam van de container in het opslagaccount. In het volgende voorbeeld wordt de naamfileuploadsgebruikt.etag: ETag om conflict met meerdere uploads te voorkomensasTtl: ISO 8601 duurstandaard, de hoeveelheid tijd die het verzoek van het apparaat om een bestand te uploaden geldig is voordat het verloopt.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:
{
"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\""
}
De configuratie van het opslagaccount voor het uploaden van bestanden ophalen
Gebruik de volgende aanvraag om details op te halen van de configuratie van een blob-opslagaccount voor het uploaden van bestanden in uw IoT Central-toepassing:
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:
{
"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\""
}
De configuratie van het opslagaccount voor het uploaden van bestanden bijwerken
Gebruik de volgende aanvraag om een blob-opslagaccount voor het uploaden van bestanden bij te werken verbindingsreeks in uw IoT Central-toepassing:
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/"
}
Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:
{
"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\""
}
De configuratie van het opslagaccount voor het uploaden van bestanden verwijderen
Gebruik de volgende aanvraag om een configuratie van een opslagaccount te verwijderen:
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Een dashboard ophalen
Gebruik de volgende aanvraag om de details van een dashboard op te halen met behulp van een dashboard-id.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:
{
"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
}
Een dashboard bijwerken
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
In het volgende voorbeeld ziet u een aanvraagbody waarmee de weergavenaam van een dashboard wordt bijgewerkt en het dashboard wordt toegevoegd aan de lijst met favorieten:
{
"displayName": "New Dashboard Name",
"favorite": true
}
Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:
{
"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
}
Een dashboard verwijderen
Gebruik de volgende aanvraag om een dashboard te verwijderen met behulp van de dashboard-id:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Dashboards weergeven
Gebruik de volgende aanvraag om een lijst met dashboards op te halen uit uw toepassing:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:
{
"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
}
]
}