Azure IoT Hub REST API 實踐

Azure IoT Hub提供了一系列的REST API 接口用來對設備，服務，以及資源進行管理。儘管在實際應用中咱們一般會選擇採用封裝的SDK，本文選擇了幾個REST API 接口進行實踐，但願須要對REST API 直接進行操做的小夥伴有所幫助。因爲幫客戶處理問題時，採用了英文回覆。我這邊就再也不作翻譯，直接貼在下面。

Test Environment Setup:

1. REST API Documentation link: https://msdn.microsoft.com/en-us/library/mt548493.aspx . This link is taking global azure IoT endpoint for example. Customer needs to adapt from 「{IoTHubName}.azure-devices.net」 to 「{IoTHubName}.azure-devices.cn」

2. A great tool I strongly suggest customer to use: Device Explorer. It is open source and can download the binary install file from this link: https://github.com/Azure/azure-iot-sdks/releases . Looking for 「SetupDeviceExplorer.msi」, and the typical installation path is: 「C:\Program Files (x86)\Microsoft\DeviceExplorer」

3. Test tool: I am using Google Postman for REST API testing. Download link: https://www.getpostman.com/docs/introduction

4. Azure IoT Hub grants access to endpoints by verifying a token against the shared access policies and device identity registry security credentials. Security credentials, such as symmetric keys, are never sent over the wire. So we need to generate SAS token from the symmetric keys. I use Device Explorer to get it in this test.

Test Result:

1. Create a device:

Put the SAS generated in Step 4 of 「Test Setup」 in the Authorization header.

 

The request body is set as below. Please note: the 「symmetricKey」 set in the request body has nothing to do with the authentication in this request. It is the key we provide for the created device. You can verify via the Device Explorer as well.

Check result from Device Explorer:

Paste request code for your reference as well:

PUT /devices/device2?api-version=2016-02-03 HTTP/1.1
Host: devpod.azure-devices.cn
Content-Type: application/json
Authorization: SharedAccessSignature sr=devpod.azure-devices.cn&sig=z%2BU9RS0mR8%2Bd8TJyfQkoaAmfnHIcIwAyZkPDw8k%2FrR4%3D&se=1509525426&skn=iothubowner
Cache-Control: no-cache
Postman-Token: 2f9f5a0b-8706-5e73-0858-257df407f0c8

{
  deviceId: "device2",
  authentication: {
   symmetricKey: {
    primaryKey: "pejHV4khao1lPbRHHVBDnhFXtzp14/XRkoC+ZfhaF28=",
			 secondaryKey: "pejHV4khao1lPbRHHVBDnhFXtzp14/XRkoC+ZfhaF28="
		 }
 	},
	 status: "enabled",
	 statusReason: "test purpose only"
 }

2. Delete a device

API reference is here: https://msdn.microsoft.com/en-us/library/azure/mt548487.aspx

Please be note: the if-Match must be set, otherwise you will get the following error.

{
  "Message": "ErrorCode:PreconditionFailed;Precondition failed: Invalid ETag",
  "ExceptionMessage": "Tracking ID:db3b5f78e7694b7cb7c5165e2ddc957a-G:0-TimeStamp:11/09/2016 07:15:55"
}

More explanation on this:

This request requires the If-Match header. The client may specify the ETag for the device identity on the request in order to compare to the ETag maintained by the service for the purpose of optimistic concurrency. The delete operation will be performed only if the ETag sent by the client matches the value maintained by the server, indicating that the device identity has not been modified since it was retrieved by the client.
To force an unconditional delete, set If-Match to the wildcard character (*).

To simplify I set If-Match to (*). Running example is shown as below.

3. Services API to check device statistics

Please be make sure your devices are connected to your IoT hub. You can check via Device Explorer.

Postman request:

Device Connection State in Device Explorer:

4. Create IoT Hub

1) Create REST API reference: https://msdn.microsoft.com/en-us/library/azure/mt589013.aspx

2) Header setting especially Authorization setting reference: https://msdn.microsoft.com/en-us/library/azure/mt589014.aspx#bk_common

3) The service management API endpoint is: management.chinacloudapi.cn, NOT management.azure.com

The most complicated part is to generate a Windows Azure AD management service access token. You can look at this link: https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal/ .

Following the steps in the link, you will get your JWT token. In the Authorization header please make sure you add 「Bearer 」 (there is a whitespace after Bearer) in the front of the JWR token.