您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

设备连接与遥测数据入口Device connectivity and telemetry ingress

设备和传感器发送的遥测数据构成了任何 IoT 解决方案的主干。The telemetry data sent by devices and sensors form the backbone of any IoT solution. 如何表示这些不同的资源并在某个位置的上下文中管理它们是 IoT 应用开发中的一个首要问题。How to represent these different resources and manage them within the context of a location are chief concerns in IoT app development. Azure 数字孪生将设备和传感器与空间智能图相结合,简化了 IoT 解决方案的开发过程。Azure Digital Twins simplifies the process of developing IoT solutions by uniting devices and sensors with a spatial intelligence graph.

若要开始,请在空间图的根位置创建 Azure IoT 中心资源。To get started, create an Azure IoT Hub resource at the root of the spatial graph. IoT 中心资源允许根空间下的所有设备发送消息。The IoT Hub resource allows all devices beneath the root space to send messages. 创建 IoT 中心后,将设备注册到数字孪生实例中的传感器。After the IoT Hub is created, register devices with sensors within the Digital Twins instance. 这些设备可以通过 Azure IoT 设备 SDK 向数字孪生服务发送数据。The devices can send data to a Digital Twins service via the Azure IoT device SDK.

有关如何将设备加入板载的循序渐进指南,请参阅部署和配置数字孪生教程For a step-by-step guide on how to bring devices onboard, read the Tutorial to deploy and configure Digital Twins. 步骤概览:At a glance, the steps are:

  • Azure 门户部署数字孪生实例。Deploy a Digital Twins instance from the Azure portal.
  • 在图中创建空间。Create spaces in your graph.
  • 创建 IoT 中心资源并将其分配到图中的某个空间。Create an IoT Hub resource, and assign it to a space in your graph.
  • 在图中创建设备和传感器,并将它们分配到上述步骤中创建的空间。Create devices and sensors in your graph, and assign them to the spaces created in the previous steps.
  • 创建匹配程序,根据条件筛选遥测消息。Create a matcher to filter telemetry messages based on conditions.
  • 创建一个用户定义的函数并将它分配到图中的某个空间,以对遥测消息进行自定义处理。Create a user-defined function, and assign it to a space in the graph for custom processing of your telemetry messages.
  • 分配角色,使用户定义的函数能够访问图中的数据。Assign a role to allow the user-defined function to access the graph data.
  • 从数字孪生管理 API 获取 IoT 中心设备连接字符串。Get the IoT Hub device connection string from the Digital Twins Management APIs.
  • 使用 Azure IoT 设备 SDK 在设备上配置设备连接字符串。Configure the device connection string on the device with the Azure IoT device SDK.

以下各部分介绍如何从数字孪生管理 API 获取 IoT 中心设备连接字符串,In the following sections, you learn how to get the IoT Hub device connection string from the Digital Twins Management API. 以及如何使用 IoT 中心遥测消息格式发送基于传感器的遥测数据。You also learn how to use the IoT Hub telemetry message format to send sensor-based telemetry. 数字孪生要求它收到的每条遥测数据都与空间图中的某个传感器相关联。Digital Twins requires each piece of telemetry that it receives to be associated with a sensor within the spatial graph. 此项要求可确保在适当的空间上下文中处理和路由数据。This requirement makes sure the data is processed and routed within the appropriate spatial context.

从管理 API 获取 IoT 中心设备连接字符串Get the IoT Hub device connection string from the Management API

在以下示例中,YOUR_MANAGEMENT_API_URL 代表数字孪生 API 的 URI:In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
名称Name 替换为Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME Azure 数字孪生实例的名称The name of your Azure Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION 托管实例的区域The region your instance is hosted on

使用 includes=ConnectionString 参数在设备 API 上执行 GET 调用,以获取 IoT 中心设备连接字符串。Do a GET call on the Device API with an includes=ConnectionString parameter to get the IoT Hub device connection string. 按设备 GUID 或硬件 ID 进行筛选以查找给定的设备。Filter by the device GUID or the hardware ID to find the given device.

YOUR_MANAGEMENT_API_URL/devices/YOUR_DEVICE_GUID?includes=ConnectionString
参数Parameter 替换为Replace with
YOUR_DEVICE_GUIDYOUR_DEVICE_GUID 设备 IDThe device ID
YOUR_MANAGEMENT_API_URL/devices?HardwareIds=YOUR_DEVICE_HARDWARE_ID&includes=ConnectionString
参数值Parameter value 替换为Replace with
YOUR_DEVICE_HARDWARE_IDYOUR_DEVICE_HARDWARE_ID 设备硬件 IDThe device hardware ID

在响应有效负载中,复制设备的 connectionString 属性。In the response payload, copy the device's connectionString property. 调用 Azure IoT 设备 SDK 以向数字孪生发送数据时,将要使用该属性。You use it when you call the Azure IoT device SDK to send data to Digital Twins.

设备到云的消息Device-to-cloud message

可以自定义设备的消息格式和有效负载,以满足解决方案的需求。You can customize your device's message format and payload to fit your solution's needs. 使用任何可以序列化为 Azure IoT Device Client Message 类 Message(byte[] byteArray) 支持的字节数组或流的数据合同。Use any data contract that can be serialized into a byte array or stream that's supported by the Azure IoT Device Client Message class, Message(byte[] byteArray). 只要在相应的用户定义函数中解码数据合同,该消息就能采用所选的自定义二进制格式。The message can be a custom binary format of your choice, as long as you decode the data contract in a corresponding user-defined function. 设备到云的消息只需满足一项要求。There's only one requirement for a device-to-cloud message. 维护一组属性以确保消息正确路由到处理引擎。Maintain a set of properties to make sure your message is routed appropriately to the processing engine.

遥测属性Telemetry properties

消息的有效负载内容可以是最大为 256 KB 的任意数据。The payload contents of a Message can be arbitrary data up to 256 KB in size. Message.Properties 类型的属性预期需要满足几项要求。There are a few requirements expected for properties of the Message.Properties type. 下表显示了系统支持的必需和可选属性。The table shows the required and optional properties supported by the system.

属性名称Property name Value 需要Required DescriptionDescription
DigitalTwins-TelemetryDigitalTwins-Telemetry 1.01.0 Yes 在系统中标识消息的常量值。A constant value that identifies a message to the system.
DigitalTwins-SensorHardwareIdDigitalTwins-SensorHardwareId string(72) Yes 发送消息的传感器的唯一标识符。A unique identifier of the sensor that sends the Message. 该值必须与对象的 HardwareId 属性匹配,以便系统可以处理它。This value must match an object's HardwareId property for the system to process it. 例如,00FF0643BE88-CO2For example, 00FF0643BE88-CO2.
CreationTimeUtcCreationTimeUtc string No ISO 8601 格式的日期字符串,用于标识有效负载的采样时间。An ISO 8601 formatted date string that identifies the sampling time of the payload. 例如,2018-09-20T07:35:00.8587882-07:00For example, 2018-09-20T07:35:00.8587882-07:00.
CorrelationIdCorrelationId string No 用于跟踪整个系统中的事件的 UUID。A UUID that's used to trace events across the system. 例如,cec16751-ab27-405d-8fe6-c68e1412ce1fFor example, cec16751-ab27-405d-8fe6-c68e1412ce1f.

将消息发送到数字孪生Send your message to Digital Twins

使用 DeviceClient SendEventAsyncSendEventBatchAsync 调用将消息发送到数字孪生。Use the DeviceClient SendEventAsync or SendEventBatchAsync call to send your message to Digital Twins.

后续步骤Next steps