IoT Hub REST

IoT Hub用の REST API は、デバイス、メッセージング、ジョブ サービス、およびリソース プロバイダーへのプログラムによるアクセスをIoT Hubで提供します。 メッセージング サービスには、Azure 内で実行されている IoT サービス内からアクセスできるほか、HTTPS 要求の送信と HTTPS 応答の受信に対応したアプリケーションからインターネット経由で直接アクセスすることもできます。

サービス

  • この API を使用して、IoT Hubデバイス ツインを管理します。 デバイス ツインのプロパティを取得および更新し、デバイスで ダイレクト メソッドを 呼び出すことができます。
  • これらの API を使用して、IoT ハブの ID レジストリ内のデバイス ID を管理します。
  • これらの API を使用して、IoT Hubでジョブを管理します。 ジョブをスケジュール、キャンセル、または取得できます。

すべてのタスク操作は HTTP/1.1 プロトコル仕様に準拠しており、各操作は要求に関する情報を取得するために使用できるヘッダーを返 x-ms-request-id します。 これらのリソースに対して行う要求には、セキュリティを確保する必要があります。 詳細については、「IoT Hub開発者ガイド - セキュリティ」を参照して、セキュリティ トークンを作成する方法の詳細を確認してください。

デバイス メッセージング

デバイスからこれらの API を使用して、デバイスからクラウドへのメッセージを IoT ハブに送信し、IoT ハブからクラウドからデバイスへのメッセージを受信します。 タスク操作はすべて、HTTP/1.1 プロトコル仕様に準拠しています。 これらのリソースに対して行う要求には、セキュリティを確保する必要があります。 詳細については、「IoT Hub開発者ガイド - セキュリティ」を参照して、セキュリティ トークンを作成する方法に関する具体的な情報を確認してください。

リソース プロバイダー

これらの API を使用して、IoT Hub リソースのデプロイを管理します。 これらの要求をセキュリティで保護する方法については、「 Azure REST API リファレンス」を参照してください

一般的なパラメーターとヘッダー

次の情報は、IoT Hubに関連するすべてのタスクに共通です。

  • {api-version} を URI の "2018-06-30" に置き換えます。

  • URI の {subscription-id} をサブスクリプション ID に置き換えます。

  • {resourceGroupName} を、IoT ハブを含む (または含まれる) リソース グループ名に置き換えます。

  • {IoTHubName} を IoT ハブの名前に置き換えます。

  • Content-Type ヘッダーは application/json に設定します。

  • 「IoT Hubセキュリティ トークンを使用する」の「セキュリティ トークン」セクションで指定したとおりに作成された SAS トークンに Authorization ヘッダーを設定します

  • Etag ヘッダーは、 RFC7232 に従って、1 つのデバイス ID をスコープとするすべての要求で返されます。

  • すべての PUT/PATCH 操作では、次のヘッダーを指定する必要があります。 If-Match = [*|<etag from get>]

  • DELETE 操作には、次のヘッダーが含まれる場合があります。 If-Match = [*|<etag from get>]

ETag の動作を次に示します。

PUT リソースが存在しない リソースが存在する
If-Match = "" / absent 201 Created 200 OK
If-Match = "*" 412 Precondition Failed 200 OK
If-Match = "xyz" 412 Precondition Failed 200 OK/ 412 前提条件に失敗しました
If-None-Match = "*" 201 Created 412 Precondition Failed
DELETE リソースが存在しない リソースが存在する
If-Match = "" / absent 204 No Content 200 OK
If-Match = "*" 204 No Content 200 OK
If-Match = "xyz" 204 No Content 200 OK/ 412 前提条件に失敗しました

非同期呼び出しの場合:

  • PUT は、非同期の操作に対して Azure-AsyncOperation ヘッダーを使用して作成された 201 で応答します。 すべての同期 (更新) 操作で 200 OK が返されます。

  • DELETE は、Location ヘッダーと Retry-After ヘッダーを含む 202 Accepted と、存在するリソースの Azure-AsyncOperation ヘッダーを返します。

  • Location ヘッダーに操作結果の URL が含まれている

  • Retry-After ヘッダーに適切な再試行間隔 (秒単位) が含まれている

  • Azure-AsyncOperation ヘッダーには、非同期操作の結果の状態の URL が含まれています

  • 完了すると、操作結果 URL への GET によって、元の操作が同期的に完了した場合とまったく同じ結果が生成されます