你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何使用 IoT Central REST API 管理数据导出

项目
07/25/2023

通过 IoT Central REST API，你可以开发与 IoT Central 应用程序集成的客户端应用程序。你可以使用 REST API 来创建和管理 IoT Central 应用程序中的数据导出。

每个 IoT Central REST API 调用都需要授权标头。有关详细信息，请参阅如何对 IoT Central REST API 调用进行身份验证和授权。

有关 IoT Central REST API 的参考文档，请参阅 Azure IoT Central REST API 参考。

提示

可以使用 Postman 尝试本文所述的 REST API 调用。下载 IoT Central Postman 集合并将其导入 Postman。在集合中需要设置变量，例如应用子域和管理员令牌。

若要了解如何使用 IoT Central UI 管理数据导出，请参阅将 IoT 数据导出到 Blob 存储。

数据导出

你可以使用 IoT Central 数据导出功能，将遥测、属性更改、设备连接事件、设备生命周期事件和设备模板生命周期事件流式传输到目标（例如 Azure 事件中心、Azure 服务总线、Azure Blob 存储和 webhook 终结点）。

每个数据导出定义可以将数据发送到一个或多个目标。创建导出定义之前，请创建目标定义。

创建或更新目标

使用以下请求创建或更新目标定义：

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

destinationId 是目标的唯一 ID。

下面的示例演示了创建 blob 存储目标的请求正文：

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

请求正文包含某些必填字段：

displayName：目标的显示名称。
type：目标对象的类型。 blobstorage@v1、dataexplorer@v1、eventhubs@v1、servicebusqueue@v1、servicebustopic@v1 或 webhook@v1 之一。
connectionString：用于访问目标资源的连接字符串。
containerName：对于 blob 存储目标，应在其中写入数据的容器的名称。

对此请求的响应如下方示例所示：

{
    "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"
}

按 ID 获取目标

使用以下请求从应用程序中检索目标的详细信息：

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

对此请求的响应如下方示例所示：

{
    "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"
}

列出目标

使用以下请求从应用程序中检索目标列表：

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

对此请求的响应如下方示例所示：

{
    "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"
        }
    ]
}

修补目标

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

可以通过此调用对导出执行增量更新。示例请求正文类似于以下示例，用于更新目标的：connectionString

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

对此请求的响应如下方示例所示：

{
    "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"
}

选择目标

使用以下请求删除目标：

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

创建或更新导出定义

使用以下请求创建或更新数据导出定义：

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

下面的示例演示了一个创建设备遥测导出定义的请求正文：

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

请求正文包含某些必填字段：

displayName：导出的显示名称。
enabled：切换到开始/停止从发送数据进行的导出。
source：要导出的数据的类型。
destinations：导出应将数据发送到的目标的列表。应用程序中必须已存在目标 ID。

有一些可选字段可用于向导出添加更多详细信息。

enrichments：每个已发送消息要包含的额外信息片段。数据表示为一组键/值对，其中键是将出现在输出消息中且值标识要发送的数据的扩充的名称。
filter：用于定义应导出源中的哪些事件的查询。

对此请求的响应如下方示例所示：

{
    "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"
}

扩充

可以向导出添加三种类型的扩充：自定义字符串、系统属性和自定义属性：

以下示例演示如何使用 enrichments 节点向传出消息添加自定义字符串：

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

以下示例演示如何使用 enrichments 节点向传出消息添加系统属性：

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

可以添加以下系统属性：

属性	说明
`$enabled`	设备是否已启用？
`$displayName`	设备名称。
`$templateDisplayName`	设备模板名称。
`$organizations`	设备所属的组织。
`$provisioned`	是否已预配设备？
`$simulated`	设备是否模拟？

以下示例演示如何使用 enrichments 节点向传出消息添加自定义属性。自定义属性是在与设备关联的设备模板中定义的属性：

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

筛选器

可以根据遥测或属性值筛选导出的消息。

以下示例演示如何使用 filter 字段仅导出加速计 X 遥测值大于 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"
}

以下示例演示如何使用 filter 字段仅导出遥测值大于 targetTemperature 属性的消息temperature：

{
  "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"
}

按 ID 获取导出

使用以下请求从应用程序中检索导出定义的详细信息：

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

对此请求的响应如下方示例所示：

{
    "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"
}

列出导出定义

使用以下请求从应用程序中导出定义的列表：

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

对此请求的响应如下方示例所示：

{
  "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"
    }
  ]
}

修补导出定义

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

可以通过此调用对导出执行增量更新。示例请求正文类似于以下示例，该示例将更新 enrichments 为导出：

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

对此请求的响应如下方示例所示：

{
    "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"
}

删除导出定义

使用以下请求删除导出定义：

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

后续步骤

现在你已了解如何使用 REST API 管理数据导出，建议接下来了解如何使用 IoT Central REST API 管理设备模板。

如何使用 IoT Central REST API 管理数据导出

数据导出

创建或更新目标

按 ID 获取目标

列出目标

修补目标

选择目标

创建或更新导出定义

扩充

筛选器

按 ID 获取导出

列出导出定义

修补导出定义

删除导出定义

后续步骤

其他资源