Partilhar via

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

  • Artigo

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ão systemAssignedManagedIdentity e connectionString.

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.