Azure IoT Hub REST API 实践

crespo09

　　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.