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.
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
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"
}
}
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.
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
É 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.
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
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.
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 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 |
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
}
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\""
}
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\""
}
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\""
}
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
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
}
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
}
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
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
}
]
}