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