مشاركة عبر

IoT Hub REST

  • مقالة

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. 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

  • Use this API to manage IoT Hub device twins. You can retrieve and update device twin properties and invoke direct methods on devices.
  • Use these APIs to manage device identities in the identity registry of an IoT hub.
  • Use these API to manage Jobs in IoT Hub. You can schedule, cancel or get a job.

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. For more information, see IoT Hub Developer Guide – Security for the specifics on how to create security tokens.

Device Messaging

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. All task operations conform to the HTTP/1.1 protocol specification. You must make sure that requests made to these resources are secure. For more information, see IoT Hub Developer Guide - Security for specific information about how to create security tokens.

Resource Provider

Use these APIs to manage the deployment of your IoT Hub resources. For information about how to secure these requests, see Azure REST API Reference.

Common parameters and headers

The following information is common to all tasks related to IoT Hub:

  • Replace {api-version} with "2018-06-30" in the URI.

  • Replace {subscription-id} with your subscription identifier in the URI.

  • Replace {resourceGroupName} with the resource group name that contains (or will contain) your IoT hub.

  • Replace {IoTHubName} with the name of your IoT hub.

  • Set the Content-Type header to application/json.

  • Set the Authorization header to a SAS token created as specified in the security tokens section of Using IoT Hub security tokens.

  • The Etag header is returned in all requests scoped to a single device identity, as per RFC7232.

  • All PUT/PATCH operations require the following headers to be specified: If-Match = [*|<etag from get>]

  • DELETE operations may include the following header: If-Match = [*|<etag from get>]

The behavior for ETags can be seen below:

PUT Resource does not exist Resource exists
If-Match = "" / absent 201 Created 200 OK
If-Match = "*" 412 Precondition Failed 200 OK
If-Match = "xyz" 412 Precondition Failed 200 OK / 412 Precondition Failed
If-None-Match = "*" 201 Created 412 Precondition Failed
DELETE Resource does not exist Resource exists
If-Match = "" / absent 204 No Content 200 OK
If-Match = "*" 204 No Content 200 OK
If-Match = "xyz" 204 No Content 200 OK / 412 Precondition Failed

For asynchronous calls:

  • PUT responds with 201 Created with Azure-AsyncOperation header for any operations that are asynchronous. All synchronous (updates) operations return 200 OK.

  • DELETE returns 202 Accepted with Location and Retry-After headers as well as Azure-AsyncOperation header for resources that exists.

  • Location header contains URL for the operation result

  • Retry-After header contains appropriate retry interval in seconds

  • Azure-AsyncOperation header contains URL for the Async operation result status

  • On completion, the GET to the operation result URL generates exactly the same result as if the original operation had completed synchronously