IoT Hub メッセージを作成し、読み取る
プロトコル間の相互運用性をサポートするために、Azure IoT Hub により、すべてのデバイスに接続するプロトコルで使用できる一般的なメッセージング機能のセットが定義されています。 これらの機能は、device-to-cloud メッセージと cloud-to-device メッセージの両方で使用できます。
Note
この記事で言及されている一部の機能 (cloud-to-device メッセージング、デバイス ツイン、デバイス管理など) は、IoT Hub の Standard レベルだけで使用することができます。 Basic および Standard または Free レベルの IoT Hub の詳細については、ソリューションに適した IoT Hub のレベルの選択に関するページを参照してください。
IoT Hub は、ストリーミング メッセージング パターンを使用して、D2C メッセージングを実装しています。 IoT Hub の device-to-cloud メッセージは、複数のリーダーで読み取り可能なサービスを経由する大量のイベントが存在するという点で、Service Bus "メッセージ" よりも Event Hubs "イベント"に似ています。
IoT Hub メッセージは、次のような構成です。
"システム プロパティ" の定義済みのセット。この記事で後述します。
一連の アプリケーション プロパティ。 メッセージ本文を逆シリアル化しなくてもアプリケーションが定義してアクセスできる、文字列プロパティのディクショナリです。 IoT Hub によってこれらのプロパティが変更されることはありません。
任意の型のデータを指定できるメッセージ本文。
各デバイス プロトコルは、さまざまな方法でプロパティの設定を実装します。 詳細については、MQTT プロトコルおよび AMQP プロトコルの開発者ガイドを参照してください。
HTTPS プロトコルを使用して device-to-cloud メッセージを送信するとき、または cloud-to-device メッセージを送信するときに、プロパティ名と値に含めることができるのは、ASCII 英数字と ! # $ % & ' * + - . ^ _ ` | ~ のみです。
IoT Hub を使用した device-to-cloud メッセージングには、次のような特徴があります。
device-to-cloud メッセージには持続性があり、最長で 7 日間、IoT hub の既定の messages/events エンドポイントに保持されます。
device-to-cloud メッセージは最大 256 KB で、バッチとしてグループ化して送信を最適化できます。 バッチは最大で 256 KB です。
IoT Hub では、任意のパーティション分割は許可されていません。 D2C メッセージは、発信元の deviceIdに基づいてパーティション分割されます。
「IoT Hub へのアクセスの制御」で説明されているように、IoT Hub ではデバイスごとに認証とアクセス制御を行うことができます。
アプリケーション プロパティに移動する情報をメッセージにスタンプできます。 詳細については、メッセージ エンリッチメントの概要に関するページを参照してください。
Note
各 IoT Hub プロトコルは、カスタム エンドポイントにデータをルーティングするときに考慮されるメッセージ コンテンツ タイプ プロパティを提供します。 送信先でデータを適切に処理するには (たとえば、JSON を Base64 でエンコードされたバイナリ データではなく解析可能な文字列として扱うなど)、メッセージに適切なコンテンツ タイプと文字セットを指定します。
IoT Hub ルーティング クエリでメッセージ本文を使うには、メッセージに有効な JSON オブジェクトを指定し、メッセージのコンテンツ タイプ プロパティを application/json;charset=utf-8 に設定します。
有効でルーティング可能なメッセージ本文の例を次に示します。
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
device-to-cloud メッセージのシステム プロパティ
| プロパティ | 説明 | ユーザー設定可能? | ルーティング クエリの キーワード |
|---|---|---|---|
| message-id | 要求/応答パターンに使用する、メッセージのユーザー設定 ID。 形式: 大文字と小文字を区別する ASCII 7 ビット英数字と - : . + % _ # * ? ! ( ) , = @ ; $ ' の文字列 (最大 128 文字)。 |
はい | messageId |
| iothub-enqueuedtime | IoT Hub が Device-to-Cloud メッセージを受信した日時。 | いいえ | enqueuedTime |
| user-id | メッセージの送信元を指定するために使用される ID。 | はい | userId |
| iothub-connection-device-id | IoT Hub で D2C メッセージに対して設定される ID。 メッセージを送信したデバイスの deviceId が含まれます。 | いいえ | connectionDeviceId |
| iothub-connection-module-id | IoT Hub で D2C メッセージに対して設定される ID。 メッセージを送信したデバイスの moduleId が含まれます。 | いいえ | connectionModuleId |
| iothub-connection-auth-generation-id | IoT Hub で D2C メッセージに対して設定される ID。 メッセージを送信したデバイスの connectionDeviceGenerationId (「デバイス ID のプロパティ」を参照) が含まれています。 | いいえ | connectionDeviceGenerationId |
| iothub-connection-auth-method | IoT Hub で D2C メッセージに対して設定される認証方法。 このプロパティには、メッセージを送信するデバイスの認証に使用する認証方法に関する情報が含まれます。 | いいえ | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | バッチ内のデータを送信するときに、デバイスがイベント作成時間を送信できるようにします。 | はい | creation-time-utc |
| iothub-creation-time-utc | 一度に 1 つのメッセージを送信するときに、デバイスがイベント作成時間を送信できるようにします。 | はい | creation-time-utc |
| dt-dataschema | この値は、IoT Hub で、device-to-cloud メッセージに対して設定されます。 デバイス接続で設定されたデバイス モデル ID が含まれます。 | いいえ | $dt-dataschema |
| dt-subject | device-to-cloud メッセージを送信しているコンポーネントの名前。 | はい | $dt-subject |
device-to-cloud メッセージのアプリケーション プロパティ
アプリケーション プロパティの一般的な用途として、デバイスからメッセージが送信された日時の記録があります。この場合、iothub-creation-time-utc プロパティを使用してデバイスからタイムスタンプを送信します。 このタイムスタンプの形式は、タイムゾーン情報を含まない UTC であることが必要です。 たとえば、2021-04-21T11:30:16Z は有効ですが、2021-04-21T11:30:16-07:00 は無効です。
{
"applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
"messageSource":"telemetry",
"deviceId":"sample-device-01",
"schema":"default@v1",
"templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
"enqueuedTime":"2021-01-29T16:45:39.143Z",
"telemetry":{
"temperature":8.341033560421833
},
"messageProperties":{
"iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
},
"enrichments":{}
}
cloud-to-device メッセージのシステム プロパティ
| プロパティ | 説明 | ユーザーが設定可能 |
|---|---|---|
| message-id | 要求/応答パターンに使用する、メッセージのユーザー設定 ID。 形式: 大文字と小文字を区別する ASCII 7 ビット英数字と - : . + % _ # * ? ! ( ) , = @ ; $ ' の文字列 (最大 128 文字)。 |
はい |
| sequence-number | IoT Hub によって各 C2D メッセージに割り当てられる数値 (デバイスとキューごとに一意)。 | いいえ |
| to | C2D メッセージで指定される宛先。 | いいえ |
| absolute-expiry-time | メッセージの有効期限の日時。 | はい |
| correlation-id | 通常、要求/応答パターンで要求の MessageId を格納する、応答メッセージの文字列プロパティ。 | はい |
| user-id | メッセージの送信元を指定するために使用される ID。 IoT Hub によってメッセージが生成される場合、ユーザー ID は IoT Hub 名になります。 | はい |
| iothub-ack | フィードバック メッセージのジェネレーター。 このプロパティは、デバイスがメッセージを使用した結果としてのフィードバック メッセージの生成を IoT Hub に要求するために、C2D メッセージで使用されます。 使用可能な値: none (既定値): フィードバック メッセージは生成されません。positive: メッセージが完了した場合にフィードバック メッセージを受信します。negative: デバイスでメッセージが完了しないまま、メッセージの有効期限が切れた場合 (または最大配信数に達した場合) にフィードバック メッセージを受信します。full: positive と negative の両方の値を意味します。 | はい |
システム プロパティ名
システム プロパティ名は、メッセージがルーティングされるエンドポイントによって異なります。
| システム プロパティ名 | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| メッセージ ID | message-id | messageId | MessageId | message-id |
| User id | user-id | userId | UserId | user-id |
| Connection device id | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Connection module id | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| Connection auth generation id | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Connection auth method | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | content-type | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | 該当なし | iothub-enqueuedtime |
| CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
メッセージ サイズ
IoT Hub では、メッセージのサイズは、プロトコルに関係なく実際のペイロードのみを考慮して測定されます。 サイズ (バイト単位) は次の値の和として計算されます。
- 本文のサイズ (バイト単位)
- メッセージ システム プロパティの全値のサイズ (バイト単位)。
- すべてのユーザー プロパティの名前と値のサイズ (バイト単位)
プロパティの名前と値は ASCII 文字に制限されているため、文字列の長さがバイト単位のサイズと等しくなります。
なりすまし対策のプロパティ
D2C メッセージでのデバイスのなりすましを回避するために、IoT Hub では、すべてのメッセージに次のプロパティを持つスタンプが使用されます。
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
最初の 2 つには、「デバイス ID プロパティ」で説明されている発信元デバイスの deviceId と generationId が含まれています。
iothub-connection-auth-method プロパティには、次のプロパティを使用してシリアル化された JSON オブジェクトが含まれています。
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
次のステップ
- IoT Hub でのメッセージ サイズの制限については、IoT Hub のクォータと調整に関するページをご覧ください。
- IoT Hub メッセージをさまざまなプログラミング言語で作成し、読み取る方法については、クイック スタートをご覧ください。
- IoT Hub によって生成される非テレメトリ イベントの構造については、IoT Hub の非テレメトリ イベント スキーマに関するページを参照してください。