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

プロトコル間でのシームレスな相互運用性をサポートするために、IoT Hub では、すべてのデバイス用プロトコルの共通のメッセージ形式が定義されています。To support seamless interoperability across protocols, IoT Hub defines a common message format for all device-facing protocols. このメッセージ形式は、device-to-cloud ルーティング メッセージと cloud-to-device メッセージの両方で使用されます。This message format is used for both device-to-cloud routing and cloud-to-device messages.

注意

この記事で言及されている一部の機能 (cloud-to-device メッセージング、デバイス ツイン、デバイス管理など) は、IoT Hub の Standard レベルだけで使用することができます。Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT Hub. IoT Hub の Basic レベルおよび Standard レベルの詳細については、適切な IoT Hub レベルの選び方に関するページを参照してください。For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

IoT Hub は、ストリーミング メッセージング パターンを使用して、D2C メッセージングを実装しています。IoT Hub implements device-to-cloud messaging using a streaming messaging pattern. IoT Hub の device-to-cloud メッセージは、Service Bus の "メッセージ" というよりはむしろ Event Hubs の "イベント" であり、複数のリーダーで読み取り可能なサービスを経由する、大量のイベントが存在します。IoT Hub's device-to-cloud messages are more like Event Hubs events than Service Bus messages in that there is a high volume of events passing through the service that can be read by multiple readers.

IoT Hub メッセージは、次のような構成です。An IoT Hub message consists of:

  • 事前定義された一連の "システム プロパティ" を以下に示します。A predetermined set of system properties as listed below.

  • 一連の アプリケーション プロパティA set of application properties. メッセージ本文を逆シリアル化しなくてもアプリケーションが定義してアクセスできる、文字列プロパティのディクショナリです。A dictionary of string properties that the application can define and access, without needing to deserialize the message body. IoT Hub によってこれらのプロパティが変更されることはありません。IoT Hub never modifies these properties.

  • 非透過的なバイナリ本文。An opaque binary body.

HTTPS プロトコルを使用して device-to-cloud メッセージを送信するとき、または cloud-to-device メッセージを送信するときに、プロパティ名と値に含めることができるのは、ASCII 英数字と {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} のみです。Property names and values can only contain ASCII alphanumeric characters, plus {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} when you send device-to-cloud messages using the HTTPS protocol or send cloud-to-device messages.

IoT Hub を使用した device-to-cloud メッセージングには、次のような特徴があります。Device-to-cloud messaging with IoT Hub has the following characteristics:

  • device-to-cloud メッセージには持続性があり、最長で 7 日間、IoT hub の既定の messages/events エンドポイントに保持されます。Device-to-cloud messages are durable and retained in an IoT hub's default messages/events endpoint for up to seven days.

  • device-to-cloud メッセージは最大 256 KB で、バッチとしてグループ化して送信を最適化できます。Device-to-cloud messages can be at most 256 KB, and can be grouped in batches to optimize sends. バッチは最大で 256 KB です。Batches can be at most 256 KB.

  • IoT Hub では、任意のパーティション分割は許可されていません。IoT Hub does not allow arbitrary partitioning. D2C メッセージは、発信元の deviceIdに基づいてパーティション分割されます。Device-to-cloud messages are partitioned based on their originating deviceId.

  • IoT Hub へのアクセスの制御」で説明されているように、IoT Hub ではデバイスごとに認証とアクセス制御を行うことができます。As explained in Control access to IoT Hub, IoT Hub enables per-device authentication and access control.

  • アプリケーション プロパティに移動する情報をメッセージにスタンプできます。You can stamp messages with information that goes into the application properties. 詳細については、メッセージ エンリッチメントに関するページを参照してください。For more information, please see message enrichments.

各種プロトコルを使用したメッセージのエンコードとデコードの方法の詳細については、Azure IoT SDK に関するページをご覧ください。For more information about how to encode and decode messages sent using different protocols, see Azure IoT SDKs.

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

プロパティProperty 説明Description ユーザーが設定可能User Settable? クエリをルーティングKeyword for
するためのキーワードrouting query
message-idmessage-id 要求/応答パターンに使用する、メッセージのユーザー設定 ID。A user-settable identifier for the message used for request-reply patterns. 形式:ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. はいYes messageIdmessageId
iothub-enqueuedtimeiothub-enqueuedtime IoT Hub が Device-to-Cloud メッセージを受信した日時。Date and time the Device-to-Cloud message was received by IoT Hub. いいえNo enqueuedTimeenqueuedTime
user-iduser-id メッセージの送信元を指定するために使用される ID。An ID used to specify the origin of messages. IoT Hub でメッセージが生成されると、 {iot hub name}に設定されます。When messages are generated by IoT Hub, it is set to {iot hub name}. はいYes userIduserId
iothub-connection-device-idiothub-connection-device-id IoT Hub で D2C メッセージに対して設定される ID。An ID set by IoT Hub on device-to-cloud messages. メッセージを送信したデバイスの deviceId が含まれます。It contains the deviceId of the device that sent the message. いいえNo connectionDeviceIdconnectionDeviceId
iothub-connection-module-idiothub-connection-module-id IoT Hub で D2C メッセージに対して設定される ID。An ID set by IoT Hub on device-to-cloud messages. メッセージを送信したデバイスの moduleId が含まれます。It contains the moduleId of the device that sent the message. いいえNo connectionModuleIdconnectionModuleId
iothub-connection-auth-generation-idiothub-connection-auth-generation-id IoT Hub で D2C メッセージに対して設定される ID。An ID set by IoT Hub on device-to-cloud messages. メッセージを送信したデバイスの connectionDeviceGenerationId (「デバイス ID のプロパティ」を参照) が含まれています。It contains the connectionDeviceGenerationId (as per Device identity properties) of the device that sent the message. いいえNo connectionDeviceGenerationIdconnectionDeviceGenerationId
iothub-connection-auth-methodiothub-connection-auth-method IoT Hub で D2C メッセージに対して設定される認証方法。An authentication method set by IoT Hub on device-to-cloud messages. このプロパティには、メッセージを送信するデバイスの認証に使用する認証方法に関する情報が含まれます。This property contains information about the authentication method used to authenticate the device sending the message. いいえNo connectionAuthMethodconnectionAuthMethod

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

プロパティProperty 説明Description ユーザーが設定可能User Settable?
message-idmessage-id 要求/応答パターンに使用する、メッセージのユーザー設定 ID。A user-settable identifier for the message used for request-reply patterns. 形式:ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. はいYes
sequence-numbersequence-number IoT Hub によって各 C2D メッセージに割り当てられる数値 (デバイスとキューごとに一意)。A number (unique per device-queue) assigned by IoT Hub to each cloud-to-device message. いいえNo
toto C2D メッセージで指定される宛先。A destination specified in Cloud-to-Device messages. いいえNo
absolute-expiry-timeabsolute-expiry-time メッセージの有効期限の日時。Date and time of message expiration. いいえNo
correlation-idcorrelation-id 通常、要求/応答パターンで要求の MessageId を格納する、応答メッセージの文字列プロパティ。A string property in a response message that typically contains the MessageId of the request, in request-reply patterns. はいYes
user-iduser-id メッセージの送信元を指定するために使用される ID。An ID used to specify the origin of messages. IoT Hub でメッセージが生成されると、 {iot hub name}に設定されます。When messages are generated by IoT Hub, it is set to {iot hub name}. はいYes
iothub-ackiothub-ack フィードバック メッセージのジェネレーター。A feedback message generator. このプロパティは、デバイスがメッセージを使用した結果としてのフィードバック メッセージの生成を IoT Hub に要求するために、C2D メッセージで使用されます。This property is used in cloud-to-device messages to request IoT Hub to generate feedback messages as a result of the consumption of the message by the device. 使用可能な値: none (既定値): フィードバック メッセージは生成されません。positive: メッセージが完了した場合にフィードバック メッセージを受信します。negative: デバイスでメッセージが完了しないまま、メッセージの有効期限が切れた場合 (または最大配信数に達した場合) にフィードバック メッセージを受信します。full: positive と negative の両方の値を意味します。Possible values: none (default): no feedback message is generated, positive: receive a feedback message if the message was completed, negative: receive a feedback message if the message expired (or maximum delivery count was reached) without being completed by the device, or full: both positive and negative. はいYes

メッセージ サイズMessage size

IoT Hub では、メッセージのサイズは、プロトコルに関係なく実際のペイロードのみを考慮して測定されます。IoT Hub measures message size in a protocol-agnostic way, considering only the actual payload. サイズ (バイト単位) は次の値の和として計算されます。The size in bytes is calculated as the sum of the following values:

  • 本文のサイズ (バイト単位)The body size in bytes.
  • メッセージ システム プロパティの全値のサイズ (バイト単位)。The size in bytes of all the values of the message system properties.
  • すべてのユーザー プロパティの名前と値のサイズ (バイト単位)The size in bytes of all user property names and values.

プロパティの名前と値は ASCII 文字に制限されているため、文字列の長さがバイト単位のサイズと等しくなります。Property names and values are limited to ASCII characters, so the length of the strings equals the size in bytes.

なりすまし対策のプロパティAnti-spoofing properties

D2C メッセージでのデバイスのなりすましを回避するために、IoT Hub では、すべてのメッセージに次のプロパティを持つスタンプが使用されます。To avoid device spoofing in device-to-cloud messages, IoT Hub stamps all messages with the following properties:

  • iothub-connection-device-idiothub-connection-device-id
  • iothub-connection-auth-generation-idiothub-connection-auth-generation-id
  • iothub-connection-auth-methodiothub-connection-auth-method

最初の 2 つには、「デバイス ID プロパティ」で説明されている発信元デバイスの deviceIdgenerationId が含まれています。The first two contain the deviceId and generationId of the originating device, as per Device identity properties.

iothub-connection-auth-method プロパティには、次のプロパティを使用してシリアル化された JSON オブジェクトが含まれています。The iothub-connection-auth-method property contains a JSON serialized object, with the following properties:

{
  "scope": "{ hub | device }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

次の手順Next steps

  • IoT Hub でのメッセージ サイズの制限については、IoT Hub のクォータと調整に関するページをご覧ください。For information about message size limits in IoT Hub, see IoT Hub quotas and throttling.

  • IoT Hub メッセージをさまざまなプログラミング言語で作成し、読み取る方法については、クイック スタートをご覧ください。To learn how to create and read IoT Hub messages in various programming languages, see the Quickstarts.