Como utilizar a API REST do IoT Central para gerir exportações de dados
A API REST do IoT Central permite desenvolver aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para criar e gerenciar exportações de dados em seu aplicativo IoT Central.
Cada chamada à API REST do IoT Central requer um cabeçalho de autorização. Para saber mais, consulte Como autenticar e autorizar chamadas de API REST do IoT Central.
Para obter a documentação de referência da API REST do IoT Central, consulte Referência da API REST do Azure IoT Central.
Para saber como gerenciar a exportação de dados usando a interface do usuário do IoT Central, consulte Exportar dados da IoT para o Armazenamento de Blobs.
Exportação de dados
Você pode usar o recurso de exportação de dados do IoT Central para transmitir telemetria, alterações de propriedade, eventos de conectividade de 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, Barramento de Serviço do Azure, Armazenamento de Blobs do Azure e pontos de extremidade de 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
Use a seguinte solicitação 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 a seguir mostra um corpo de solicitação que cria um destino de armazenamento de blob:
{
"displayName": "Blob Storage",
"type": "blobstorage@v1",
"authorization": {
"type": "systemAssignedManagedIdentity",
"endpointUri": "https://yourapplication.blob.core.windows.net/",
"containerName": "central-data"
}
}
O corpo da solicitação tem alguns campos obrigatórios:
displayName: Nome de exibição do destino.type: Tipo de objeto de destino. Um de:blobstorage@v1,dataexplorer@v1, ,eventhubs@v1,servicebusqueue@v1,webhook@v1servicebustopic@v1.authorization: Os detalhes da autorização para o destino. Os tipos de autorização suportados sãosystemAssignedManagedIdentityeconnectionString.
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
"displayName": "Blob Storage",
"type": "blobstorage@v1",
"authorization": {
"type": "systemAssignedManagedIdentity",
"endpointUri": "https://yourapplication.blob.core.windows.net/",
"containerName": "central-data"
},
"status": "waiting"
}
Obter um destino por ID
Use a seguinte solicitação para recuperar detalhes de um destino do seu aplicativo:
GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
"displayName": "Blob Storage",
"type": "blobstorage@v1",
"authorization": {
"type": "systemAssignedManagedIdentity",
"endpointUri": "https://yourapplication.blob.core.windows.net/",
"containerName": "central-data"
},
"status": "waiting"
}
Listar destinos
Use a seguinte solicitação para recuperar uma lista de destinos do seu aplicativo:
GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"value": [
{
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
"displayName": "Blob Storage Destination",
"type": "blobstorage@v1",
"authorization": {
"type": "systemAssignedManagedIdentity",
"endpointUri": "https://yourapplication.blob.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
Você pode usar essa chamada para executar uma atualização incremental para uma exportação. O corpo da solicitação de exemplo se parece com o exemplo a seguir que atualiza o containerName de um destino:
{
"containerName": "central-data-analysis"
}
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
"displayName": "Blob Storage",
"type": "blobstorage@v1",
"authorization": {
"type": "systemAssignedManagedIdentity",
"endpointUri": "https://yourapplication.blob.core.windows.net/",
"containerName": "central-data-analysis"
},
"status": "waiting"
}
Excluir um destino
Use a seguinte solicitação para excluir 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
Use a seguinte solicitação 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 a seguir mostra um corpo de solicitação que cria uma definição de exportação para telemetria de dispositivo:
{
"displayName": "Enriched Export",
"enabled": true,
"source": "telemetry",
"enrichments": {
"Custom data": {
"value": "My value"
}
},
"destinations": [
{
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
}
]
}
O corpo da solicitação tem alguns campos obrigatórios:
displayName: Nome de exibição da exportação.enabled: Alterne 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á devem existir no aplicativo.
Existem alguns campos opcionais que você pode usar para adicionar mais detalhes à exportação.
enrichments: Informações extras a serem incluídas em cada mensagem enviada. Os dados são representados como um conjunto de pares chave/valor, onde a chave é o nome do enriquecimento a ser exibido na mensagem de saída e o valor identifica os dados a serem enviados.filter: Consulta que define quais eventos da origem devem ser exportados.
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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
Há três tipos de enriquecimento que você pode adicionar a uma exportação: cadeias de caracteres personalizadas, propriedades do sistema e propriedades personalizadas:
O exemplo a seguir mostra como usar o enrichments nó para adicionar uma cadeia de caracteres personalizada à mensagem de saída:
"enrichments": {
"My custom string": {
"value": "My value"
},
//...
}
O exemplo a seguir mostra como usar o enrichments nó para adicionar uma propriedade system à mensagem de saída:
"enrichments": {
"Device template": {
"path": "$templateDisplayName"
},
//...
}
Você pode adicionar as seguintes propriedades do sistema:
| Property | Description |
|---|---|
$enabled |
O dispositivo está ativado? |
$displayName |
O nome do dispositivo. |
$templateDisplayName |
O nome do modelo de dispositivo. |
$organizations |
As organizações às quais o dispositivo pertence. |
$provisioned |
O dispositivo é provisionado? |
$simulated |
O dispositivo é simulado? |
O exemplo a seguir mostra como usar o enrichments nó para adicionar uma propriedade personalizada à mensagem de saída. 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
Você pode filtrar as mensagens exportadas com base em valores de telemetria ou propriedade.
O exemplo a seguir mostra como usar o filter campo para exportar somente mensagens em que o valor de telemetria acelerômetro-X é maior que 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 a seguir mostra como usar o filter campo para exportar somente mensagens em que o valor de telemetria temperature é maior 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
Use a seguinte solicitação para recuperar detalhes de uma definição de exportação do seu aplicativo:
GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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"
}
Listar definições de exportação
Use a seguinte solicitação para recuperar uma lista de definições de exportação do seu aplicativo:
GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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
Você pode usar essa chamada para executar uma atualização incremental para uma exportação. O corpo da solicitação de exemplo se parece com o exemplo a seguir que atualiza o enrichments para uma exportação:
{
"enrichments": {
"Custom data": {
"value": "My value 2"
}
}
}
A resposta a essa solicitação se parece com o exemplo a seguir:
{
"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"
}
Excluir uma definição de exportação
Use a seguinte solicitação para excluir uma definição de exportação:
DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview
Próximos passos
Agora que você aprendeu como gerenciar a exportação de dados com a API REST, uma próxima etapa sugerida é Como usar a API REST do IoT Central para gerenciar modelos de dispositivo.