Update: from preview to GA there are two main changes for this article:
1) new api version: 2018-06-30
2) the applyConfigurationContent is now requiring a modulesContent object (previously was moduleContent)
In this article you will find some example code snippets to create a new Azure IoT Edge Device programmatically and send it a deployment.json (via REST API)
Authenticate the HTTP Requests:#
Each REST request to the IoT Hub endpoint must be authenticated; in order to do that you need to retrieve a SAS Token. To better understand how the Azure IoT Hub Security works, I suggest you to read this official documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
using System;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using System.Web;
class Program
{
static void Main(string[] args)
{
createToken("iotedgedev-iothub-79024e.azure-devices.net",
"iothubowner",
"thebase64encodedkey/cUM2BK3eWc=");
}
private static void createToken(string resourceUri, string keyName, string key)
{
//For example we decided to create a token expiring in a week
TimeSpan sinceEpoch = DateTime.UtcNow - new DateTime(1970, 1, 1);
var week = 60 * 60 * 24 * 7;
var expiry = Convert.ToString((int)sinceEpoch.TotalSeconds + week);
//IoT Hub Security docs here: https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-security
string stringToSign = HttpUtility.UrlEncode(resourceUri) + "\n" + expiry;
HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String(key));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign)));
var sasToken = String.Format(CultureInfo.InvariantCulture,
"SharedAccessSignature sr={0}&sig={1}&se={2}&skn={3}",
HttpUtility.UrlEncode(resourceUri),
HttpUtility.UrlEncode(signature),
expiry,
keyName);
Console.WriteLine(sasToken);
}
}
|
Create your Edge Device:#
Request:
1
2
3
|
PUT https://{iot-hub-name}.azure-devices.net/devices/{edge-device-name}?api-version=2018-06-30
Authorization: {the key obtained with the C# snippet before}
Content-Type: application/json
|
Body:
1
2
3
4
5
6
|
{
"deviceId": "edge-device-name",
"capabilities": {
"iotEdge": true
}
}
|
Sample response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
{
"deviceId": "edge-device-name",
"generationId": "636579134228272173",
"etag": "MjE0MDgyNTg0",
"connectionState": "Disconnected",
"status": "enabled",
"statusReason": null,
"connectionStateUpdatedTime": "0001-01-01T00:00:00",
"statusUpdatedTime": "0001-01-01T00:00:00",
"lastActivityTime": "0001-01-01T00:00:00",
"cloudToDeviceMessageCount": 0,
"authentication": {
"symmetricKey": {
"primaryKey": "base64primarykey",
"secondaryKey": "base64secondarykey"
},
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"type": "sas"
},
"capabilities": {
"iotEdge": true
}
}
|
Apply a deployment.json to the newly created IoT Edge Device:#
Request:
1
2
3
|
POST https://{iot-hub-name}.azure-devices.net/devices/{edge-device-name}/applyConfigurationContent?api-version=2018-06-30
Authorization: {the key obtained with the C# snippet before}
Content-Type: application/json
|
Body:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
|
{
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.0",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": ""
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.0.2",
"createOptions": ""
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.0.2",
"createOptions": ""
}
}
},
"modules": {
"yourModule": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "yourRepository/yourModule:yourTag",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.0",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
}
}
}
|
Sample response:
204 - No content
If you want, you can find other Azure IoT related articles here