IoT Central REST API を使用してデータエクスポートを管理する方法

[アーティクル]
07/25/2023

IoT Central REST API を使用して、IoT Central アプリケーションと統合するクライアントアプリケーションを開発できます。 REST API を使用して、IoT Central アプリケーションでデータエクスポートの作成と管理を行えます。

すべての IoT Central REST API 呼び出しに承認ヘッダーが必要です。詳細については、「IoT Central REST API 呼び出しを認証および承認する方法」を参照してください。

IoT Central REST API のリファレンスドキュメントについては、「Azure IoT Central REST API リファレンス」をご覧ください。

ヒント

Postman を使用して、この記事で説明されている REST API 呼び出しを試してみることができます。 IoT Central Postman コレクションをダウンロードし、Postman にインポートしてください。コレクションでは、アプリのサブドメインや管理者トークンなどの変数を設定する必要があります。

IoT Central UI を使用してデータエクスポートを管理する方法については、「IoT データを Blob Storage にエクスポートする」を参照してください。

データのエクスポート

IoT Central のデータエクスポート機能を使用すると、テレメトリ、プロパティの変更、デバイス接続イベント、デバイスライフサイクルイベント、デバイステンプレートライフサイクルイベントを、Azure Event Hubs、Azure Service Bus、Azure Blob Storage、Webhook エンドポイントなどの宛先にストリーミングできます。

各データエクスポート定義では、1 つ以上の宛先にデータを送信できます。エクスポート定義を作成する前に、宛先の定義を作成します。

宛先を作成または更新する

次の要求を使用して、宛先定義を作成または更新します。

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId は宛先の一意の ID です。

次の例は、BLOB ストレージの宛先を作成する要求本文を示しています。

{
  "displayName": "Blob Storage Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
  "containerName": "central-data"
}

要求本文には、いくつかの必須フィールドがあります。

displayName: 宛先の表示名。
type: 変換先オブジェクトタイプ。 blobstorage@v1、dataexplorer@v1、eventhubs@v1、servicebusqueue@v1、servicebustopic@v1、webhook@v1 のいずれかです。
connectionString: 宛先リソースにアクセスするための接続文字列。
containerName: BLOB ストレージの宛先の場合、データを書き込むコンテナーの名前。

この要求に対する応答は、次の例のようになります。

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

ID で宛先を取得する

アプリケーションから宛先の詳細を取得するには、次の要求を使用します。

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

この要求に対する応答は、次の例のようになります。

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

宛先のリスト

アプリケーションから宛先のリストを取得するには、次の要求を使用します。

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

この要求に対する応答は、次の例のようになります。

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
                "type": "connectionString",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
                "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

宛先の修正

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

この呼び出しを使用して、エクスポートへの増分更新を実行できます。サンプル要求本文は、宛先のを connectionString 更新する次の例のようになります。

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net"
}

この要求に対する応答は、次の例のようになります。

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

宛先の削除

宛先を削除するには、次の要求を使用します。

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

エクスポート定義を作成または更新する

次の要求を使用して、データエクスポート定義を作成または更新します。

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

次の例は、デバイステレメトリ用のエクスポート定義を作成する要求本文を示しています。

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

要求本文には、いくつかの必須フィールドがあります。

displayName: エクスポートの表示名。
enabled: エクスポートのデータ送信を開始/停止する切り替え。
source: エクスポートするデータの種類。
destinations: エクスポートのデータ送信先となる宛先の一覧。宛先の ID は、アプリケーションに既に存在している必要があります。

エクスポートに詳細を追加するために使用できる、いくつかの省略可能なフィールドがあります。

enrichments: 送信される各メッセージに含める追加の情報。データはキーと値のペアのセットとして表されます。ここで、キーは出力メッセージに表示されるエンリッチメントの名前であり、値は送信するデータを識別します。
filter: ソースからエクスポートするイベントを定義するクエリ。

この要求に対する応答は、次の例のようになります。

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

エンリッチメント

エクスポートに追加できるエンリッチメントには、カスタム文字列、システムプロパティ、カスタムプロパティの 3 種類があります。

次の例は、ノードを enrichments 使用して送信メッセージにカスタム文字列を追加する方法を示しています。

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

次の例は、ノードを enrichments 使用して送信メッセージにシステムプロパティを追加する方法を示しています。

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

次のシステムプロパティを追加できます。

プロパティ	説明
`$enabled`	デバイスは有効になっていますか?
`$displayName`	デバイス名。
`$templateDisplayName`	デバイステンプレート名。
`$organizations`	デバイスが属している組織。
`$provisioned`	デバイスはプロビジョニングされていますか?
`$simulated`	デバイスはシミュレートされていますか?

次の例は、ノードを使用 enrichments して送信メッセージにカスタムプロパティを追加する方法を示しています。カスタムプロパティは、デバイスが関連付けられているデバイステンプレートで定義されているプロパティです。

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

フィルター

テレメトリまたはプロパティ値に基づいて、エクスポートされたメッセージをフィルター処理できます。

次の例では、フィールドを使用 filter して、accelerometer-X テレメトリ値が 0 より大きいメッセージのみをエクスポートする方法を示します。

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

次の例では、フィールドを使用 filter して、テレメトリ値が temperature プロパティより大きいメッセージのみをエクスポートする方法を targetTemperature 示します。

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

ID でエクスポートを取得する

アプリケーションからエクスポート定義の詳細を取得するには、次の要求を使用します。

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

この要求に対する応答は、次の例のようになります。

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage Destination",
    "type": "blobstorage@v1",
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
    "containerName": "central-data",
    "status": "waiting"
}

エクスポート定義のリスト

アプリケーションからエクスポート定義のリストを取得するには、次の要求を使用します。

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

この要求に対する応答は、次の例のようになります。

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

エクスポート定義を更新する

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

この呼び出しを使用して、エクスポートへの増分更新を実行できます。サンプル要求本文は、次の例のようになります。ここでは、エクスポートの enrichments が更新されます。

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

この要求に対する応答は、次の例のようになります。

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

エクスポート定義を削除する

エクスポート定義を削除するには、次の要求を使用します。

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

次の手順

REST API を使用してデータエクスポートを管理する方法を学習したので、推奨される次のステップは「IoT Central REST API を使用してデバイステンプレートを管理する方法」です。

IoT Central REST API を使用してデータ エクスポートを管理する方法

データのエクスポート

宛先を作成または更新する

ID で宛先を取得する

宛先のリスト

宛先の修正

宛先の削除

エクスポート定義を作成または更新する

エンリッチメント

フィルター

ID でエクスポートを取得する

エクスポート定義のリスト

エクスポート定義を更新する

エクスポート定義を削除する

次の手順

その他のリソース

IoT Central REST API を使用してデータエクスポートを管理する方法