デバイスの接続性とテレメトリの受信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 Digital Twins は、デバイスやセンサーと空間インテリジェンス グラフを統合することにより、IoT ソリューションの開発のプロセスを簡単にします。Azure Digital Twins simplifies the process of developing IoT solutions by uniting devices and sensors with a spatial intelligence graph.

まず、空間グラフのルートに Azure IoT Hub のリソースを作成します。To get started, create an Azure IoT Hub resource at the root of the spatial graph. IoT Hub のリソースにより、メッセージを送信するルート空間の下ですべてのデバイスが許可されます。The IoT Hub resource allows all devices beneath the root space to send messages. IoT ハブが作成されたら、Digital Twins のインスタンス内のセンサーにデバイスを登録します。After the IoT Hub is created, register devices with sensors within the Digital Twins instance. デバイスは、Azure IoT device SDK 経由で Digital Twins サービスにデータを送信することができます。The devices can send data to a Digital Twins service via the Azure IoT device SDK.

デバイスをオンボードする方法の詳しい手順については、Digital Twins のデプロイと構成に関するチュートリアルの記事をご覧ください。For a step-by-step guide on how to bring devices onboard, see the Tutorial to deploy and configure Digital Twins. 手順の概要は次のとおりです。At a glance, the steps are:

  • Azure portal から Digital Twins のインスタンスをデプロイします。Deploy a Digital Twins instance from the Azure portal.
  • グラフに空間を作成します。Create spaces in your graph.
  • IoT Hub リソースを作成し、グラフ内の空間に割り当てます。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.
  • Digital Twins Management API から IoT Hub デバイスの接続文字列を取得します。Get the IoT Hub device connection string from the Digital Twins Management APIs.
  • Azure IoT device SDK を使用してデバイスにデバイス接続文字列を構成します。Configure the device connection string on the device with the Azure IoT device SDK.

次のセクションで、Digital Twins Management API から IoT Hub デバイスの接続文字列を取得する方法について説明します。In the following sections, you learn how to get the IoT Hub device connection string from the Digital Twins Management API. また、IoT Hub のテレメトリ メッセージの形式を使用してセンサー ベースのテレメトリを送信する方法を説明します。You also learn how to use the IoT Hub telemetry message format to send sensor-based telemetry. Digital Twins は、受信したテレメトリの各部分が空間グラフ内のセンサーに関連付けられることを必要とします。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.

Management API から IoT Hub デバイスの接続文字列を取得するGet the IoT Hub device connection string from the Management API

次の例では、YOUR_MANAGEMENT_API_URL は Digital Twins 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
NameName 置換後の文字列Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME Azure Digital Twins インスタンスの名前The name of your Azure Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION インスタンスをホストするリージョンThe region your instance is hosted on

includes=ConnectionString パラメーターを指定して Device API で GET 呼び出しを行い、IoT Hub デバイスの接続文字列を取得します。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 device SDK を呼び出して Digital Twins にデータを送信する際に使用します。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. デバイスからクラウドへのメッセージの要件は 1 つだけあります。There's only one requirement for a device-to-cloud message. 処理エンジンにメッセージが適切にルーティングされるようにプロパティのセットを維持する必要があります。You must maintain a set of properties to make sure your message is routed appropriately to the processing engine.

テレメトリのプロパティTelemetry properties

Message のペイロードの内容はサイズが最大 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 説明Description
DigitalTwins-TelemetryDigitalTwins-Telemetry 1.01.0 はいYes システムに対してメッセージを示す定数値。A constant value that identifies a message to the system.
DigitalTwins-SensorHardwareIdDigitalTwins-SensorHardwareId string(72) はいYes Message を送信しているセンサーの一意識別子。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-CO2 」のように入力します。For 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:00 」のように入力します。For 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-c68e1412ce1f 」のように入力します。For example, cec16751-ab27-405d-8fe6-c68e1412ce1f.

Digital Twins へのメッセージの送信Send your message to Digital Twins

DeviceClient の SendEventAsync または SendEventBatchAsync の呼び出しを使用して、メッセージを Digital Twins に送信します。Use the DeviceClient SendEventAsync or SendEventBatchAsync call to send your message to Digital Twins.

次の手順Next steps