Usar a API REST para criar e gerenciar aplicativos do IoT Central
Você pode usar o painel de controle da API REST para criar e gerenciar aplicativos do IoT Central. Você também pode usar a API REST para:
- Adicionar 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 recurso management.azure.com. 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.
Teste seus aplicativos
Para obter uma lista de 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 de 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
Você pode recuperar os detalhes de um aplicativo individual:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Criar um aplicativo IoT Central
Para criar um aplicativo do IoT Central com uma identidade gerenciada atribuída pelo 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
O conteúdo 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 de exibição e habilitar a identidade gerenciada atribuída pelo 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 o conteúdo a seguir para alterar o nome de exibição e habilitar a identidade gerenciada atribuída pelo sistema:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Observação
Você só pode adicionar uma identidade gerenciada a um aplicativo do IoT Central criado em uma região. Todos os novos aplicativos são criados em uma região.
Excluir um aplicativo do IoT Central
Use isso para excluir um aplicativo do IoT Central:
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
É possível criar painéis associados a uma organização específica. Um painel de organizações só fica visível para os usuários que têm acesso à organização à que o painel está associado. Somente os usuários em uma função que têm as permissões de painel de organizações podem criar, editar e excluir os painéis de organizações.
Todos os usuários podem criar painéis pessoais, visíveis apenas para eles mesmos. Os usuários podem alternar entre painéis de organização e painéis pessoais.
Observação
No momento, não há suporte para a criação de painéis pessoais usando a API.
Para saber como gerenciar painéis usando a IU do IoT Central, confira Como gerenciar painéis.
API REST de painéis
A API REST do IoT Central permite:
- Adicionar um painel ao aplicativo
- Atualizar um painel no aplicativo
- Obter uma lista do painel no aplicativo
- Obter um painel por ID
- Excluir um painel no aplicativo
Adicionar um painel
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 de exibição do painel.@favorite: o painel está na lista de favoritos?group: ID do grupo de dispositivos.Tile: configuração que especifica um objeto de bloco, incluindo o layout, o nome de exibição e a configuração.
O bloco tem alguns campos obrigatórios:
| Nome | Descrição |
|---|---|
displayName |
Nome de exibição do bloco |
height |
Altura do bloco |
width |
Largura do bloco |
x |
Posição horizontal do bloco |
y |
Posição vertical do bloco |
As dimensões e a localização de um bloco usam unidades inteiras. O menor bloco possível tem altura e largura igual a um.
É possível configurar um objeto de bloco para exibir diversos tipos de dados. Este artigo inclui exemplos de blocos que mostram gráficos de linhas, reduções e o último valor conhecido. Para saber mais sobre os diferentes tipos de bloco que podem ser adicionados a um painel, confira Tipos de bloco.
Bloco Gráfico de linhas
Fazem a plotagem de um ou mais valores agregados de telemetria para um ou mais dispositivos ao longo de um período. Por exemplo, você pode exibir um gráfico de linhas para fazer a plotagem da temperatura e pressão médias de um ou mais dispositivos na última hora.
O bloco do gráfico de linhas tem a seguinte configuração:
| Nome | Descrição |
|---|---|
capabilities |
Especifica o valor agregado da telemetria que será exibido. |
devices |
A lista de dispositivos que serão exibidos. |
format |
A configuração do formato do gráfico, como os eixos que serão usados. |
group |
A ID do grupo de dispositivos que será exibida. |
queryRange |
O intervalo de tempo e a resolução que serão exibidos. |
type |
lineChart |
Bloco de redução
Bloco clicável que exibe um título e uma descrição cujo texto é formatado usando Markdown. A URL pode ser um link relativo a outra página do aplicativo ou um link absoluto para um site externo. O bloco de redução tem a seguinte configuração:
| Nome | Descrição |
|---|---|
description |
A cadeia de caracteres de redução que será renderizada no bloco. |
href |
O link que será visitado ao selecionar o bloco. |
image |
Uma imagem codificada em base64 que será exibida. |
type |
markdown |
Bloco de último valor conhecido
Exibe os valores de telemetria mais recentes para um ou mais dispositivos. Por exemplo, você pode usar esses blocos para exibir os valores mais recentes de temperatura, pressão e umidade para um ou mais dispositivos.
O bloco do LKV (último valor conhecido) tem a seguinte configuração:
| Nome | Descrição |
|---|---|
capabilities |
Especifica a telemetria que será exibida. |
devices |
A lista de dispositivos que serão exibidos. |
format |
A configuração de formato do bloco de LKV, como o tamanho do texto da quebra de linha. |
group |
A ID do grupo de dispositivos que será exibida. |
showTrend |
Mostra 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 painel com blocos de gráfico de linha, redução e último valor conhecido. Os blocos de LKV e gráfico de linhas são blocos 2x2. O bloco de redução é um bloco 1x1. Os blocos são organizados 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 é parecida com o seguinte exemplo:
{
"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
}
Adicionar uma configuração da conta de armazenamento de upload de arquivo
Use a seguinte solicitação para criar uma configuração de conta de armazenamento de blobs de upload de arquivos no aplicativo IoT Central:
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
O corpo da solicitação tem os campos a seguir:
account: o nome da conta de armazenamento onde o arquivo será carregado.connectionString: a cadeia de conexão a ser conectada à conta de armazenamento.container: o nome do contêiner na conta de armazenamento. O seguinte exemplo usa o nomefileuploads.etag: ETag para evitar conflitos com vários uploadssasTtl: padrão de duração ISO 8601. O prazo de validade da solicitação do dispositivo para carregar um arquivo antes de expirar.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
A resposta a essa solicitação é parecida com o seguinte exemplo:
{
"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\""
}
Obter a configuração da conta de armazenamento de upload de arquivo
Use a seguinte solicitação para recuperar os detalhes de uma configuração de conta de armazenamento de blobs de upload de arquivos no aplicativo IoT Central:
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
A resposta a essa solicitação é parecida com o seguinte exemplo:
{
"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\""
}
Atualizar a configuração da conta de armazenamento de upload de arquivo
Use a seguinte solicitação para atualizar uma cadeia de conexão de conta de armazenamento de blobs de upload de arquivos no aplicativo 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/"
}
A resposta a essa solicitação é parecida com o seguinte exemplo:
{
"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\""
}
Remover a configuração da conta de armazenamento de upload de arquivo
Use a solicitação a seguir para excluir uma configuração de conta de armazenamento:
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
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 é parecida com o seguinte exemplo:
{
"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 de exibição de um painel e adiciona o painel à lista de favoritos:
{
"displayName": "New Dashboard Name",
"favorite": true
}
A resposta a essa solicitação é parecida com o seguinte exemplo:
{
"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
}
Excluir um dashboard
Use a seguinte solicitação para excluir um painel usando a ID dele:
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 aplicativo:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
A resposta a essa solicitação é parecida com o seguinte exemplo:
{
"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
}
]
}