IoT Hub RESTIoT Hub REST

IoT Hub 用 REST API は、IoT Hub のデバイス、メッセージング、およびジョブ サービス、およびリソース プロバイダーへのプログラムによるアクセスを提供します。The REST APIs for IoT Hub offer programmatic access to the device, messaging, and job services, as well as the resource provider, in IoT Hub. メッセージング サービスには、Azure 内で実行されている IoT サービス内からアクセスできるほか、HTTPS 要求の送信と HTTPS 応答の受信に対応したアプリケーションからインターネット経由で直接アクセスすることもできます。You can access messaging services from within an IoT service running in Azure, or directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response.

サービスService

  • この API を使用して IoT Hubデバイス ツインを管理します。Use this API to manage IoT Hub device twins. デバイス ツインプロパティを取得および更新し、デバイスでダイレクト メソッドを呼び出すことができます。You can retrieve and update device twin properties and invoke direct methods on devices.
  • これらの API を使用して、IoT ハブの ID レジストリでデバイス ID を管理します。Use these APIs to manage device identities in the identity registry of an IoT hub.
  • IoT Hub でジョブを管理するには、これらの API を使用します。Use these API to manage Jobs in IoT Hub. ジョブのスケジュール設定、キャンセル、取得ができます。You can schedule, cancel or get a job.

すべてのタスク操作は HTTP/1.1 プロトコル仕様に準拠しており、各x-ms-request-id操作は要求に関する情報を取得するために使用できるヘッダーを返します。All task operations conform to the HTTP/1.1 protocol specification and each operation returns an x-ms-request-id header that can be used to obtain information about the request. これらのリソースに対して行う要求には、セキュリティを確保する必要があります。You must make sure that requests made to these resources are secure. 詳細については、「IoT Hub 開発者ガイド - セキュリティ トークンの作成方法に関する詳細については、「セキュリティ」を参照してください。For more information, see IoT Hub Developer Guide – Security for the specifics on how to create security tokens.

デバイスメッセージングDevice Messaging

デバイスからこれらの API を使用して、デバイスからクラウドへのメッセージを IoT ハブに送信し、IoT ハブからクラウドからデバイスへのメッセージを受信します。Use these APIs from a device to send device-to-cloud messages to an IoT hub, and receive cloud-to-device messages from an IoT hub. タスク操作はすべて、HTTP/1.1 プロトコル仕様に準拠しています。All task operations conform to the HTTP/1.1 protocol specification. これらのリソースに対して行う要求には、セキュリティを確保する必要があります。You must make sure that requests made to these resources are secure. 詳細については、「IoT Hub 開発者ガイド - セキュリティ トークンの作成方法に関する特定の情報」を参照してください。For more information, see IoT Hub Developer Guide - Security for specific information about how to create security tokens.

リソース プロバイダーResource Provider

これらの API を使用して、IoT Hub リソースのデプロイを管理します。Use these APIs to manage the deployment of your IoT Hub resources. これらの要求をセキュリティで保護する方法については、「 Azure REST API リファレンス 」を参照してくださいFor information about how to secure these requests, see Azure REST API Reference.

一般的なパラメーターとヘッダーCommon parameters and headers

IoT Hub に関連するすべてのタスクに共通の情報を次に示します。The following information is common to all tasks related to IoT Hub:

  • URI 内の {api-version} を "2018-06-30" に置き換えます。Replace {api-version} with "2018-06-30" in the URI.

  • URI の {subscription-id} をサブスクリプション ID に置き換えます。Replace {subscription-id} with your subscription identifier in the URI.

  • {リソース グループ名} を、IoT ハブを含む (または含む) リソース グループ名に置き換えます。Replace {resourceGroupName} with the resource group name that contains (or will contain) your IoT hub.

  • {IoTHubName} を IoT ハブの名前に置き換えます。Replace {IoTHubName} with the name of your IoT hub.

  • Content-Type ヘッダーは application/json に設定します。Set the Content-Type header to application/json.

  • 承認ヘッダーを、IoT Hubセキュリティ トークンの使用 のセキュリティ トークンセクションで指定された SAS トークンに設定します。Set the Authorization header to a SAS token created as specified in the security tokens section of Using IoT Hub security tokens.

  • Etag ヘッダーは、RFC7232に従って、単一のデバイス ID にスコープされるすべての要求で返されます。The Etag header is returned in all requests scoped to a single device identity, as per RFC7232.

  • すべての PUT/PATCH 操作では、以下のヘッダーを指定する必要があります。If-Match = [*|<etag from get>]All PUT/PATCH operations require the following headers to be specified: If-Match = [*|<etag from get>]

  • DELETE 操作には、次のヘッダーが含まれます。If-Match = [*|<etag from get>]DELETE operations may include the following header: If-Match = [*|<etag from get>]

ETag の動作は以下のようになります。The behavior for ETags can be seen below:

PUTPUT リソースが存在しませんResource does not exist リソースが存在しますResource exists
一致する場合 = "" /不在If-Match = "" / absent 201 Created201 Created 200 OK200 OK
IF マッチ = "*"If-Match = "*" 412 Precondition Failed412 Precondition Failed 200 OK200 OK
If-マッチ = "xyz"If-Match = "xyz" 412 Precondition Failed412 Precondition Failed 200 OK/ 412 前提条件が失敗しました200 OK / 412 Precondition Failed
If-None-一致 = "*"If-None-Match = "*" 201 Created201 Created 412 Precondition Failed412 Precondition Failed
DELETEDELETE リソースが存在しませんResource does not exist リソースが存在しますResource exists
一致する場合 = "" /不在If-Match = "" / absent 204 No Content204 No Content 200 OK200 OK
IF マッチ = "*"If-Match = "*" 204 No Content204 No Content 200 OK200 OK
If-マッチ = "xyz"If-Match = "xyz" 204 No Content204 No Content 200 OK/ 412 前提条件が失敗しました200 OK / 412 Precondition Failed

非同期呼び出しの場合:For asynchronous calls:

  • PUT は、非同期操作の場合は、Azure-AsyncOperation ヘッダーで作成された 201 で応答します。PUT responds with 201 Created with Azure-AsyncOperation header for any operations that are asynchronous. すべての同期 (更新) 操作は 200 OK を返します。All synchronous (updates) operations return 200 OK.

  • DELETE は、存在するリソースの Azure-AsyncOperation ヘッダーと同様に、場所と再試行後のヘッダーで 202 承認済み 202 を返します。DELETE returns 202 Accepted with Location and Retry-After headers as well as Azure-AsyncOperation header for resources that exists.

  • ロケーションヘッダーには操作結果の URL が含まれていますLocation header contains URL for the operation result

  • 再試行後ヘッダーには、適切な再試行間隔が秒単位で含まれていますRetry-After header contains appropriate retry interval in seconds

  • Azure-非同期操作のヘッダーには、非同期操作の結果の状態の URL が含まれています。Azure-AsyncOperation header contains URL for the Async operation result status

  • 完了時に、操作結果 URL への GET は、元の操作が同期的に完了した場合とまったく同じ結果を生成します。On completion, the GET to the operation result URL generates exactly the same result as if the original operation had completed synchronously