Usar a API REST para criar e gerenciar aplicativos do IoT Central
Você pode usar a API REST do plano de controle para criar e gerenciar aplicativos do IoT Central. Você também pode usar a API REST para:
- Adicione uma identidade gerenciada ao seu aplicativo.
- Gerenciar painéis em seu aplicativo
Para usar essa API, você precisa de um token de portador para o management.azure.com recurso. Para obter um token de portador, você pode usar a CLI do Azure:
az account get-access-token --resource https://management.azure.com
Para saber como gerenciar o aplicativo IoT Central usando a interface do usuário do IoT Central, consulte Criar um aplicativo do IoT Central.
Liste suas aplicações
Para obter uma lista dos aplicativos do IoT Central em uma assinatura:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Para obter uma lista dos aplicativos do IoT Central em um grupo de recursos:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Pode obter os detalhes de um pedido individual:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Criar uma aplicação de IoT Central
Para criar um aplicativo IoT Central com uma identidade gerenciada atribuída ao sistema:
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
A carga útil a seguir mostra a configuração para o novo aplicativo, incluindo a identidade gerenciada:
{
"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"
}
}
Modificar um aplicativo do IoT Central
Você pode modificar um aplicativo existente do IoT Central. O exemplo a seguir mostra como alterar o nome para exibição e habilitar a identidade gerenciada atribuída ao sistema:
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
Use a seguinte carga para alterar o nome de exibição e habilitar a identidade gerenciada atribuída ao sistema:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Nota
Você só pode adicionar uma identidade gerenciada a um aplicativo do IoT Central que foi criado em uma região. Todos os novos aplicativos são criados em uma região.
Excluir um aplicativo do IoT Central
Para excluir um aplicativo do IoT Central, use:
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
Você pode criar painéis associados a uma organização específica. Um painel da organização só é visível para os usuários que têm acesso à organização à qual o painel está associado. Somente os usuários em uma função que tenha permissões de painel da organização podem criar, editar e excluir painéis da organização.
Todos os usuários podem criar painéis pessoais, visíveis apenas para si mesmos. Os usuários podem alternar entre a organização e painéis pessoais.
Nota
No momento, não há suporte para a criação de painéis pessoais usando API.
Para saber como gerenciar painéis usando a interface do usuário do IoT Central, consulte Como gerenciar painéis.
API REST de painéis
A API REST do IoT Central permite:
- Adicionar um painel ao seu aplicativo
- Atualizar um painel em seu aplicativo
- Obter uma lista do painel no aplicativo
- Obter um painel por ID
- Excluir um painel em seu aplicativo
Adicionar um dashboard
Use a solicitação a seguir para criar um painel.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId- Um identificador DTMI exclusivo para o painel.
O corpo da solicitação tem alguns campos obrigatórios:
@displayName: Nome para exibição do painel.@favorite: O painel está na lista de favoritos?group: ID do grupo de dispositivos.Tile: Configuração especificando objeto de bloco, incluindo o layout, nome para exibição e configuração.
O mosaico tem alguns campos obrigatórios:
| Nome | Descrição |
|---|---|
displayName |
Nome para exibição do bloco |
height |
Altura da telha |
width |
Largura do mosaico |
x |
Posição horizontal da telha |
y |
Posição vertical do mosaico |
As dimensões e a localização de um bloco usam unidades inteiras. A menor telha possível tem uma altura e largura de uma.
Você pode configurar um objeto de bloco para exibir vários tipos de dados. Este artigo inclui exemplos de blocos que mostram gráficos de linhas, markdown e o último valor conhecido. Para saber mais sobre os diferentes tipos de mosaico que pode adicionar a um dashboard, consulte Tipos de mosaico.
Mosaico do gráfico de linhas
Plotar um ou mais valores agregados de telemetria para um ou mais dispositivos durante um período de tempo. Por exemplo, você pode exibir um gráfico de linhas para plotar a temperatura média e a pressão de um ou mais dispositivos durante a última hora.
O bloco de gráfico de linhas tem a seguinte configuração:
| Nome | Descrição |
|---|---|
capabilities |
Especifica o valor agregado da telemetria a ser exibida. |
devices |
A lista de dispositivos a serem exibidos. |
format |
A configuração de formato do gráfico, como os eixos a serem usados. |
group |
A ID do grupo de dispositivos a ser exibido. |
queryRange |
O intervalo de tempo e a resolução a serem exibidos. |
type |
lineChart |
Mosaico Markdown
Blocos clicáveis que exibem um título e um texto de descrição formatados em Markdown. O URL pode ser um link relativo para outra página no aplicativo ou um link absoluto para um site externo. O bloco de marcação tem a seguinte configuração:
| Nome | Descrição |
|---|---|
description |
A cadeia de caracteres de markdown a ser renderizada dentro do bloco. |
href |
O link a ser visitado quando o bloco for selecionado. |
image |
Uma imagem codificada em base64 para exibir. |
type |
markdown |
Último bloco de valor conhecido
Exiba os valores de telemetria mais recentes para um ou mais dispositivos. Por exemplo, você pode usar esse bloco para exibir os valores mais recentes de temperatura, pressão e umidade para um ou mais dispositivos.
O último bloco de valor conhecido (LKV) tem a seguinte configuração:
| Nome | Descrição |
|---|---|
capabilities |
Especifica a telemetria a ser exibida. |
devices |
A lista de dispositivos a serem exibidos. |
format |
A configuração de formato do bloco LKV, como o tamanho do texto da quebra automática de texto. |
group |
A ID do grupo de dispositivos a ser exibido. |
showTrend |
Mostrar a diferença entre o último valor conhecido e o valor anterior. |
type |
lkv |
O exemplo a seguir mostra um corpo de solicitação que adiciona um novo painel com gráfico de linhas, marcação e blocos do último valor conhecido. Os blocos LKV e gráfico de linhas são 2x2 blocos. O bloco de marcação é um 1x1 bloco. Os blocos estão dispostos na linha superior do painel:
{
"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
}
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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
}
Obter um painel
Use a solicitação a seguir para recuperar os detalhes de um painel usando uma ID de painel.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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
}
Atualizar um painel
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
O exemplo a seguir mostra um corpo de solicitação que atualiza o nome para exibição de um painel e adiciona o painel à lista de favoritos:
{
"displayName": "New Dashboard Name",
"favorite": true
}
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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
}
Eliminar um dashboard
Use a seguinte solicitação para excluir um painel usando a ID do painel:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Listar painéis
Use a seguinte solicitação para recuperar uma lista de painéis do seu aplicativo:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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
}
]
}