Share via

Como utilizar a API REST do IoT Central para gerir exportações de dados

  • Artigo

A API REST do IoT Central permite-lhe desenvolver aplicações cliente que se integram com aplicações do IoT Central. Pode utilizar a API REST para criar e gerir exportações de dados na sua aplicação do IoT Central.

Cada chamada à API REST do IoT Central requer um cabeçalho de autorização. Para saber mais, veja Como autenticar e autorizar chamadas à API REST do IoT Central.

Para obter a documentação de referência da API REST do IoT Central, veja Referência da API REST do Azure IoT Central.

Dica

Pode utilizar o Postman para experimentar as chamadas à API REST descritas neste artigo. Transfira a coleção do Postman do IoT Central e importe-a para o Postman. Na coleção, terá de definir variáveis como o subdomínio da aplicação e o token de administrador.

Para saber como gerir a exportação de dados com a IU do IoT Central, veja Exportar dados de IoT para o Armazenamento de Blobs.

Exportação de dados

Pode utilizar a funcionalidade de exportação de dados do IoT Central para transmitir telemetria, alterações de propriedades, eventos de conectividade do dispositivo, eventos de ciclo de vida do dispositivo e eventos de ciclo de vida do modelo de dispositivo para destinos como Hubs de Eventos do Azure, Azure Service Bus, Armazenamento de Blobs do Azure e pontos finais do webhook.

Cada definição de exportação de dados pode enviar dados para um ou mais destinos. Crie as definições de destino antes de criar a definição de exportação.

Criar ou atualizar um destino

Utilize o seguinte pedido para criar ou atualizar uma definição de destino:

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId é um ID exclusivo para o destino.

O exemplo seguinte mostra um corpo do pedido que cria um destino de armazenamento de blobs:

{
  "displayName": "Blob Storage Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
  "containerName": "central-data"
}

O corpo do pedido tem alguns campos necessários:

  • displayName: nome a apresentar do destino.
  • type: tipo de objeto de destino. Um de: blobstorage@v1, dataexplorer@v1, , servicebusqueue@v1eventhubs@v1, servicebustopic@v1, . webhook@v1
  • connectionString: a cadeia de ligação para aceder ao recurso de destino.
  • containerName: para um destino de armazenamento de blobs, o nome do contentor onde os dados devem ser escritos.

A resposta a este pedido tem o seguinte exemplo:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Obter um destino por ID

Utilize o seguinte pedido para obter detalhes de um destino da sua aplicação:

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

A resposta a este pedido tem o seguinte exemplo:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Listar destinos

Utilize o seguinte pedido para obter uma lista de destinos da sua aplicação:

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

A resposta a este pedido tem o seguinte exemplo:

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
                "type": "connectionString",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
                "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

Corrigir um destino

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Pode utilizar esta chamada para efetuar uma atualização incremental para uma exportação. O corpo do pedido de exemplo tem o seguinte exemplo que atualiza o connectionString de um destino:

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net"
}

A resposta a este pedido tem o seguinte exemplo:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

Eliminar um destino

Utilize o seguinte pedido para eliminar um destino:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Criar ou atualizar uma definição de exportação

Utilize o seguinte pedido para criar ou atualizar uma definição de exportação de dados:

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

O exemplo seguinte mostra um corpo do pedido que cria uma definição de exportação para a telemetria do dispositivo:

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

O corpo do pedido tem alguns campos necessários:

  • displayName: nome a apresentar da exportação.
  • enabled: Alternar para iniciar/impedir que uma exportação envie dados.
  • source: o tipo de dados a exportar.
  • destinations: a lista de destinos para os quais a exportação deve enviar dados. Os IDs de destino já têm de existir na aplicação.

Existem alguns campos opcionais que pode utilizar para adicionar mais detalhes à exportação.

  • enrichments: informações adicionais a incluir com cada mensagem enviada. Os dados são representados como um conjunto de pares chave/valor, em que a chave é o nome do melhoramento que será apresentado na mensagem de saída e o valor identifica os dados a enviar.
  • filter: Consulta que define que eventos da origem devem ser exportados.

A resposta a este pedido tem o seguinte exemplo:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

Melhoramentos

Existem três tipos de melhoramento que pode adicionar a uma exportação: cadeias personalizadas, propriedades do sistema e propriedades personalizadas:

O exemplo seguinte mostra como utilizar o enrichments nó para adicionar uma cadeia personalizada à mensagem de envio:

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

O exemplo seguinte mostra como utilizar o enrichments nó para adicionar uma propriedade do sistema à mensagem de envio:

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

Pode adicionar as seguintes propriedades do sistema:

Propriedade Descrição
$enabled O dispositivo está ativado?
$displayName O nome do dispositivo.
$templateDisplayName O nome do modelo do dispositivo.
$organizations As organizações a que pertence o dispositivo.
$provisioned O dispositivo está aprovisionado?
$simulated O dispositivo está simulado?

O exemplo seguinte mostra como utilizar o enrichments nó para adicionar uma propriedade personalizada à mensagem de envio. As propriedades personalizadas são propriedades definidas no modelo de dispositivo ao qual o dispositivo está associado:

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

Filtros

Pode filtrar as mensagens exportadas com base em valores de telemetria ou propriedade.

O exemplo seguinte mostra como utilizar o filter campo para exportar apenas mensagens em que o valor de telemetria accelerometer-X é superior a 0:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

O exemplo seguinte mostra como utilizar o filter campo para exportar apenas mensagens em que o temperature valor de telemetria é maior do que a targetTemperature propriedade:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

Obter uma exportação por ID

Utilize o seguinte pedido para obter detalhes de uma definição de exportação da sua aplicação:

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

A resposta a este pedido tem o seguinte exemplo:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage Destination",
    "type": "blobstorage@v1",
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
    "containerName": "central-data",
    "status": "waiting"
}

Listar definições de exportação

Utilize o seguinte pedido para obter uma lista de definições de exportação da sua aplicação:

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

A resposta a este pedido tem o seguinte exemplo:

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

Corrigir uma definição de exportação

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

Pode utilizar esta chamada para efetuar uma atualização incremental para uma exportação. O corpo do pedido de exemplo tem o seguinte exemplo que atualiza o enrichments para uma exportação:

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

A resposta a este pedido tem o seguinte exemplo:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

Eliminar uma definição de exportação

Utilize o seguinte pedido para eliminar uma definição de exportação:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

Passos seguintes

Agora que aprendeu a gerir a exportação de dados com a API REST, um passo seguinte sugerido é Como utilizar a API REST do IoT Central para gerir modelos de dispositivos.