Event Grid を使用し IoT Hub のイベントに対応してアクションをトリガーするReact to IoT Hub events by using Event Grid to trigger actions

他のサービスにイベント通知を送信して、ダウンストリームのプロセスをトリガーできるように、Azure IoT Hub は Azure Event Grid と統合します。Azure IoT Hub integrates with Azure Event Grid so that you can send event notifications to other services and trigger downstream processes. 信頼性が高く、スケーラブルで、安全な方法により、重大なイベントに対応できるよう、IoT Hub のイベントをリッスンするようにビジネス アプリケーションを構成します。Configure your business applications to listen for IoT Hub events so that you can react to critical events in a reliable, scalable, and secure manner. たとえば、新しい IoT デバイスが IoT Hub に登録されるたびに、データベースの更新、作業チケットの作成、メール通知の配信などを実行するよう、アプリケーションを構築します。 For example, build an application that updates a database, creates a work ticket, and delivers an email notification every time a new IoT device is registered to your IoT hub.

Azure Event Grid は、発行-サブスクライブ モデルを使う、フル マネージドのイベント ルーティング サービスです。Azure Event Grid is a fully managed event routing service that uses a publish-subscribe model. Event Grid は、Azure FunctionsAzure Logic Apps などの Azure s サービスの組み込みサポートを備えており、webhook を使って Azure 以外のサービスにイベント アラートを配信できます。Event Grid has built-in support for Azure services like Azure Functions and Azure Logic Apps, and can deliver event alerts to non-Azure services using webhooks. Event Grid がサポートするイベント ハンドラーの完全な一覧については、「Azure Event Grid の概要」をご覧ください。For a complete list of the event handlers that Event Grid supports, see An introduction to Azure Event Grid.

Azure Event Grid のアーキテクチャ

リージョン別の提供状況Regional availability

Event Grid の統合は、Event Grid イベントグリッドがサポートされている地域にある IoT ハブで利用できます。The Event Grid integration is available for IoT hubs located in the regions where Event Grid is supported. 最新のリージョン一覧については、「Azure Event Grid の概要」を参照してください。For the latest list of regions, see An introduction to Azure Event Grid.

イベントの種類Event types

IoT Hub は次のイベントの種類を発行します。IoT Hub publishes the following event types:

イベントの種類Event type 説明Description
Microsoft.Devices.DeviceCreatedMicrosoft.Devices.DeviceCreated デバイスが IoT Hub に登録されると発行されます。Published when a device is registered to an IoT hub.
Microsoft.Devices.DeviceDeletedMicrosoft.Devices.DeviceDeleted デバイスが IoT Hub から削除されると発行されます。Published when a device is deleted from an IoT hub.
Microsoft.Devices.DeviceConnectedMicrosoft.Devices.DeviceConnected デバイスが IoT Hub に接続されると発行されます。Published when a device is connected to an IoT hub.
Microsoft.Devices.DeviceDisconnectedMicrosoft.Devices.DeviceDisconnected デバイスが IoT Hub から切断されると発行されます。Published when a device is disconnected from an IoT hub.
Microsoft.Devices.DeviceTelemetryMicrosoft.Devices.DeviceTelemetry デバイス テレメトリのメッセージが IoT Hub に送信されると発行されますPublished when a device telemetry message is sent to an IoT hub

各 IoT Hub から発行するイベントを構成するには、Azure Portal または Azure CLI を使います。Use either the Azure portal or Azure CLI to configure which events to publish from each IoT hub. 例については、チュートリアル「Logic Apps を使用して Azure IoT Hub イベントに関する電子メール通知を送信する」をお試しください。For an example, try the tutorial Send email notifications about Azure IoT Hub events using Logic Apps.

イベント スキーマEvent schema

IoT Hub イベントには、デバイスのライフサイクルの変更に対応するために必要なすべての情報が含まれます。IoT Hub events contain all the information you need to respond to changes in your device lifecycle. eventType プロパティが Microsoft.Devices で始まることをチェックすることにより、IoT Hub イベントを識別できます。You can identify an IoT Hub event by checking that the eventType property starts with Microsoft.Devices. Event Grid イベント プロパティの使い方について詳しくは、「Event Grid イベント スキーマ」をご覧ください。For more information about how to use Event Grid event properties, see the Event Grid event schema.

デバイス接続スキーマDevice connected schema

次の例では、デバイス接続イベントのスキーマを示します。The following example shows the schema of a device connected event:

[{  
  "id": "f6bbf8f4-d365-520d-a878-17bf7238abd8",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceConnected",
  "eventTime": "2018-06-02T19:17:44.4383997Z",
  "data": {
      "deviceConnectionStateEventInfo": {
        "sequenceNumber":
          "000000000000000001D4132452F67CE200000002000000000000000000000001"
      },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice",
    "moduleId" : "DeviceModuleID",
  }, 
  "dataVersion": "1",
  "metadataVersion": "1"
}]

デバイス テレメトリ スキーマDevice Telemetry schema

デバイス テレメトリ メッセージは、メッセージのシステム プロパティで contentType が application/json に設定され、contentEncoding が UTF-8 に設定された有効な JSON 形式である必要があります。Device telemetry message must be in a valid JSON format with the contentType set to application/json and contentEncoding set to UTF-8 in the message system properties. これらのプロパティでは、どちらも大文字と小文字が区別されません。Both of these properties are case insensitive. コンテンツのエンコードが設定されていない場合、IoT Hub では Base 64 エンコード形式でメッセージが書き込まれます。If the content encoding is not set, then IoT Hub will write the messages in base 64 encoded format.

エンドポイントを Event Grid として選択してデバイス テレメトリ イベントを Event Grid に発行する前に、それらをエンリッチすることができます。You can enrich device telemetry events before they are published to Event Grid by selecting the endpoint as Event Grid. 詳細については、メッセージ エンリッチメントの概要に関するページを参照してください。For more information, see Message Enrichments Overview.

次の例に、デバイス テレメトリ イベントのスキーマを示します。The following example shows the schema of a device telemetry event:

[{  
  "id": "9af86784-8d40-fe2g-8b2a-bab65e106785",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceTelemetry",
  "eventTime": "2019-01-07T20:58:30.48Z",
  "data": {
      "body": {
          "Weather": {
              "Temperature": 900
            },
            "Location": "USA"
        },
        "properties": {
            "Status": "Active"
        },
        "systemProperties": {
          "iothub-content-type": "application/json",
          "iothub-content-encoding": "utf-8",
          "iothub-connection-device-id": "d1",
          "iothub-connection-auth-method": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
          "iothub-connection-auth-generation-id": "123455432199234570",
          "iothub-enqueuedtime": "2019-01-07T20:58:30.48Z",
          "iothub-message-source": "Telemetry"
        }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

デバイスで作成されたスキーマDevice created schema

次の例では、デバイス作成スキーマを示します。The following example shows the schema of a device created event:

[{
  "id": "56afc886-767b-d359-d59e-0da7877166b2",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceCreated",
  "eventTime": "2018-01-02T19:17:44.4383997Z",
  "data": {
    "twin": {
      "deviceId": "LogicAppTestDevice",
      "etag": "AAAAAAAAAAE=",
      "deviceEtag":"null",
      "status": "enabled",
      "statusUpdateTime": "0001-01-01T00:00:00",
      "connectionState": "Disconnected",
      "lastActivityTime": "0001-01-01T00:00:00",
      "cloudToDeviceMessageCount": 0,
      "authenticationType": "sas",
      "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
      },
      "version": 2,
      "properties": {
        "desired": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        },
        "reported": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        }
      }
    },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

各プロパティの詳しい説明については、「IoT Hub の Azure Event Grid イベント スキーマ」をご覧ください。For a detailed description of each property, see Azure Event Grid event schema for IoT Hub.

イベントのフィルター処理Filter events

IoT Hub イベント サブスクリプションでは、イベントの種類、データ コンテンツ、およびサブジェクト (デバイス名) に基づいてイベントをフィルター処理できます。IoT Hub event subscriptions can filter events based on event type, data content and subject, which is the device name.

Event Grid により、イベントの種類、サブジェクト、およびデータ コンテンツでフィルター処理できます。Event Grid enables filtering on event types, subjects and data content. Event Grid サブスクリプションの作成時に、選択した IoT イベントにサブスクライブするように選択できます。While creating the Event Grid subscription, you can choose to subscribe to selected IoT events. Event Grid のサブジェクト フィルターは、Begins With (プレフィックス) と Ends With (サフィックス) の一致に基づいて動作します。Subject filters in Event Grid work based on Begins With (prefix) and Ends With (suffix) matches. フィルターは AND 演算子を使用するため、プレフィックスとサフィックスの両方に一致するサブジェクトを持つイベントがサブスクライバーに配信されます。The filter uses an AND operator, so events with a subject that match both the prefix and suffix are delivered to the subscriber.

IoT イベントのサブジェクトには次の形式が使われます。The subject of IoT Events uses the format:

devices/{deviceId}

さらに、Event Grid では、データ コンテンツなどの各イベントの属性でフィルター処理することもできます。Event Grid also allows for filtering on attributes of each event, including the data content. これにより、テレメトリ メッセージの内容に基づいて配信されるイベントを選択することができます。This allows you to choose what events are delivered based contents of the telemetry message. 高度なフィルター処理を参照して、例を確認してください。Please see advanced filtering to view examples. テレメトリ メッセージ本文のフィルター処理の場合、メッセージのシステム プロパティで contentType を application/json に設定し、contentEncoding を UTF-8 に設定する必要があります。For filtering on the telemetry message body, you must set the contentType to application/json and contentEncoding to UTF-8 in the message system properties. これらのプロパティでは、どちらも大文字と小文字が区別されません。Both of these properties are case insensitive.

DeviceConnected、DeviceDisconnected、DeviceCreated、DeviceDeleted のような非テレメトリ イベントの場合、サブスクリプションの作成時に Event Grid のフィルター処理を使用できます。For non-telemetry events like DeviceConnected, DeviceDisconnected, DeviceCreated and DeviceDeleted, the Event Grid filtering can be used when creating the subscription. テレメトリ イベントの場合、Event Grid でのフィルター処理に加えて、ユーザーは、メッセージ ルーティング クエリ経由で、デバイス ツイン、メッセージのプロパティと本文に対してフィルター処理することもできます。For telemetry events, in addition to the filtering in Event Grid, users can also filter on device twins, message properties and body through the message routing query.

Event Grid 経由でテレメトリ イベントをサブスクライブすると、IoT Hub では、Event Grid にデータ ソース型のデバイス メッセージを送信するための既定のメッセージ ルートが作成されます。When you subscribe to telemetry events via Event Grid, IoT Hub creates a default message route to send data source type device messages to Event Grid. メッセージ ルーティングの詳細については、IoT Hub メッセージ ルーティングに関するページを参照してください。For more information about message routing, see IoT Hub message routing. このルートはポータルの [IoT Hub] の [メッセージ ルーティング] に表示されます。This route will be visible in the portal under IoT Hub > Message Routing. Event Grid までの唯一のルートは、テレメトリ イベントに対して作成される EG サブスクリプションの数に関係なく作成されます。Only one route to Event Grid is created regardless of the number of EG subscriptions created for telemetry events. そのため、フィルターの異なるサブスクリプションがいくつか必要な場合、同じルートでこれらのクエリに OR 演算子を使用できます。So, if you need several subscriptions with different filters, you can use the OR operator in these queries on the same route. ルートの作成と削除は、Event Grid 経由のテレメトリ イベントのサブスクリプションによって制御されます。The creation and deletion of the route is controlled through subscription of telemetry events via Event Grid. IoT Hub メッセージ ルーティングを利用して Event Grid までのルートを作成したり、削除したりすることはできません。You cannot create or delete a route to Event Grid using IoT Hub Message Routing.

テレメトリ データが送信される前に、メッセージをフィルター処理するために、ルーティング クエリを更新できます。To filter messages before telemetry data is sent, you can update your routing query. ルーティング クエリは本文が JSON である場合にのみ、メッセージ本文に適用できることに注意してください。Note that routing query can be applied to the message body only if the body is JSON. また、メッセージのシステム プロパティで contentType を application/json に設定し、contentEncoding を UTF-8 に設定する必要もあります。You must also set the contentType to application/json and contentEncoding to UTF-8 in the message system properties.

デバイス接続イベントおよびデバイス切断イベントの制限事項Limitations for device connected and device disconnected events

デバイス接続状態イベントを受信するには、デバイスで IoT Hub を使用して "D2C テレメトリ送信" または "C2D メッセージ受信" 操作を実行する必要があります。To receive device connection state events, a device must do either a 'D2C Send Telemetry' OR a 'C2D Receive Message' operation with Iot Hub. しかし、AMQP プロトコルを使用して IoT Hub に接続するデバイスについては、"C2D メッセージ受信" 操作を実行することが推奨されます。そうしないと、接続状態の通知が数分遅延することがあります。However, note that if a device is using AMQP protocol to connect with Iot Hub, it is recommended that they do a 'C2D Receive Message' operation otherwise their connection state notifications may be delayed by few minutes. デバイスが MQTT プロトコルを使用している場合、IoT Hub は C2D リンクを開いたままにします。If your device is using MQTT protocol, IoT Hub will keep the C2D link open. AMQP では、Receive Async API (IoT Hub C# SDK) またはデバイス クライアント (AMQP) を呼び出すことによって C2D リンクを開くことができます。For AMQP, you can open the C2D link by calling the Receive Async API, for IoT Hub C# SDK, or device client for AMQP.

テレメトリを送信する場合は、D2C リンクが開いています。The D2C link is open if you are sending telemetry.

デバイスの接続状態が頻繁に変化する場合、つまりデバイスが頻繁に接続されたり切断されたりする場合は、1 つ 1 つの接続状態が送信されるのではなく、接続状態が変化し続ける間、定期的なスナップショットで取得される最新の接続状態が公開されます。If the device connection is flickering, which means the device connects and disconnects frequently, we will not send every single connection state, but will publish the current connection state taken at a periodic snapshot, till the flickering continues. 異なるシーケンス番号で同じ接続状態イベントを受信する場合も、異なる接続状態イベントを受信する場合も、デバイスの接続状態に変化が生じたことを意味します。Receiving either the same connection state event with different sequence numbers or different connection state events both mean that there was a change in the device connection state.

イベントの使用に関するヒントTips for consuming events

IoT Hub イベントを処理するアプリケーションは、以下の推奨される手法に従う必要があります。Applications that handle IoT Hub events should follow these suggested practices:

  • 同じイベント ハンドラーにイベントをルーティングするように複数のサブスクリプションを構成できるので、イベントが特定のソースからであると想定しないでください。Multiple subscriptions can be configured to route events to the same event handler, so don't assume that events are from a particular source. 常にメッセージ トピックをチェックし、予期される IoT Hub からものであることを確認してください。Always check the message topic to ensure that it comes from the IoT hub that you expect.

  • 受信するすべてのイベントが予期する種類であると想定してはいけません。Don't assume that all events you receive are the types that you expect. メッセージを処理する前に、常に eventType をチェックしてください。Always check the eventType before processing the message.

  • メッセージは、順不同で、または遅延の後に、到着する場合があります。Messages can arrive out of order or after a delay. etag フィールドを使って、デバイス作成イベントやデバイス削除イベントについて、オブジェクトに関する情報が最新かどうかを確認してください。Use the etag field to understand if your information about objects is up-to-date for device created or device deleted events.

次のステップNext steps