Como usar a API REST do IoT Central para gerenciar a exportação de dados
A API REST do IoT Central permite que você desenvolva aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para criar e gerenciar exportação de dados em seu aplicativo do IoT Central.
Cada chamada à API REST do IoT Central exige um cabeçalho de autorização. Para saber mais, confira Como autenticar e autorizar chamadas à API REST do IoT Central.
Para obter a documentação de referência da API REST do IoT Central, confira 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 de IoT para o Armazenamento de Blobs.
Exportação de dados
É possível usar o recurso de exportação de dados do IoT Central para transmitir telemetria, alterações de propriedade, 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, 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 é uma ID exclusiva do destino.
O exemplo a seguir mostra um corpo de solicitação que cria um destino de Armazenamento de BLOBs:
{
"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. Uma opção entreblobstorage@v1,dataexplorer@v1,eventhubs@v1,servicebusqueue@v1,servicebustopic@v1ouwebhook@v1.authorization: Os detalhes da autorização para o destino. Os tipos de autorização suportados sãosystemAssignedManagedIdentityeconnectionString.
A resposta a essa solicitação é parecida com o seguinte exemplo:
{
"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 solicitação a seguir 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 é parecida com o seguinte exemplo:
{
"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"
}
Lista de destinos
Use a solicitação a seguir 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 é parecida com o seguinte exemplo:
{
"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 esta 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 é parecida com o seguinte exemplo:
{
"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 do 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/parar uma exportação do envio de dados.source: O tipo de dados a exportação.destinations: A lista de destinos para os quais a exportação deve enviar dados. As IDs de destino já devem existir no aplicativo.
Há 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 de chave/valor, em que a chave é o nome do enriquecimento que deve aparecer 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 é parecida com 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"
}
Enriquecimentos
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 nó enrichments 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 nó enrichments para adicionar uma propriedade do sistema à mensagem de saída:
"enrichments": {
"Device template": {
"path": "$templateDisplayName"
},
//...
}
Você pode adicionar as seguintes propriedades do sistema:
| Propriedade | Descrição |
|---|---|
$enabled |
O dispositivo está habilitado? |
$displayName |
O nome do dispositivo. |
$templateDisplayName |
O nome do modelo do 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 nó enrichments 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 nos valores de telemetria ou propriedade.
O exemplo a seguir mostra como usar o campo filter para exportar somente mensagens em que o valor de telemetria accelerometer-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 campo filter para exportar somente mensagens em que o valor de telemetria temperature é maior que a propriedade targetTemperature:
{
"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 solicitação a seguir 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 é parecida com o seguinte exemplo:
{
"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 solicitação a seguir 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 é parecida com 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"
}
]
}
Aplicar patch em uma definição de exportação
PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview
Você pode usar esta chamada para executar uma atualização incremental para uma exportação. O corpo da solicitação de amostra é semelhante ao exemplo a seguir, que atualiza o enrichments para uma exportação:
{
"enrichments": {
"Custom data": {
"value": "My value 2"
}
}
}
A resposta a essa solicitação é parecida com 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"
}
Excluir um patch em 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óximas etapas
Agora que você aprendeu a gerenciara 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.