IoT Hub メッセージを作成し、読み取る

  • [アーティクル]

プロトコル間のシームレスな相互運用性をサポートするために、Azure IoT Hub では、すべてのデバイスに接続するプロトコルで使用できる一般的なメッセージング機能のセットを定義しています。 これらは、デバイスからクラウドへのメッセージ ルーティングとクラウドからデバイスへのメッセージの両方で使用できます。

Note

この記事で言及されている一部の機能 (cloud-to-device メッセージング、デバイス ツイン、デバイス管理など) は、IoT Hub の Standard レベルだけで使用することができます。 Basic および Standard または Free レベルの IoT Hub の詳細については、ソリューションに適した IoT Hub のレベルの選択に関するページを参照してください。

IoT Hub は、ストリーミング メッセージング パターンを使用して、D2C メッセージングを実装しています。 IoT Hub の D2C メッセージは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 ではデバイスごとに認証とアクセス制御を行うことができます。

  • アプリケーション プロパティに移動する情報をメッセージにスタンプできます。 詳細については、メッセージ エンリッチメントに関するページを参照してください。

各種プロトコルを使用したメッセージのエンコードとデコードの方法の詳細については、Azure IoT SDK に関するページをご覧ください。

Note

各 IoT Hub プロトコルは、カスタム エンドポイントにデータをルーティングするときに考慮されるメッセージ コンテンツ タイプ プロパティを提供します。 コピー先でデータを適切に処理するには (たとえば、Base64 でエンコードされたバイナリ データではなく、解析可能な文字列として扱われる JSON など)、メッセージの適切なコンテンツ タイプと文字セットを指定する必要があります。

IoT Hub ルーティング クエリでメッセージ本文を使用するには、メッセージの有効な JSON オブジェクトを指定し、メッセージのコンテンツ タイプ プロパティをapplication/json;charset=utf-8に設定する必要があります。

有効でルーティング可能なメッセージ本文は、次のようになります。

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

D2C IoT Hub メッセージのシステム プロパティ

プロパティ 説明 ユーザー設定可能? ルーティング クエリの
キーワード
message-id 要求/応答パターンに使用する、メッセージのユーザー設定 ID。 形式:ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}。 はい messageId
iothub-enqueuedtime IoT Hub が Device-to-Cloud メッセージを受信した日時。 いいえ enqueuedTime
user-id メッセージの送信元を指定するために使用される ID。 IoT Hub でメッセージが生成されると、 {iot hub name}に設定されます。 はい 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

D2C IoT Hub メッセージのアプリケーション プロパティ

アプリケーション プロパティの一般的な用途として、デバイスからメッセージが送信された日時の記録があります。この場合、iothub-creation-time-utc プロパティを使用してデバイスからタイムスタンプを送信します。 このタイムスタンプの形式は、タイムゾーン情報を含まない UTC であることが必要です。 たとえば 2021-04-21T11:30:16Z は有効ですが、2021-04-21T11:30:16-07:00 は有効ではありません。

{
  "applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
  "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":{}
}

C2D IoT Hub メッセージのシステム プロパティ

プロパティ 説明 ユーザーが設定可能
message-id 要求/応答パターンに使用する、メッセージのユーザー設定 ID。 形式:ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}。 はい
sequence-number IoT Hub によって各 C2D メッセージに割り当てられる数値 (デバイスとキューごとに一意)。 いいえ
to C2D メッセージで指定される宛先。 いいえ
absolute-expiry-time メッセージの有効期限の日時。 はい
correlation-id 通常、要求/応答パターンで要求の MessageId を格納する、応答メッセージの文字列プロパティ。 はい
user-id メッセージの送信元を指定するために使用される ID。 IoT Hub でメッセージが生成されると、 {iot hub name}に設定されます。 はい
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"
}

次のステップ