You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
#CustomerIntent: As an industrial edge IT or operations user, I want configure my Azure IoT Operations environment so that I can access data from HTTP/REST endpoints.
11
11
---
12
12
13
13
# Configure the connector for REST/HTTP (preview)
14
14
15
-
In Azure IoT Operations, the connector for REST/HTTP (preview) enables access to data from HTTP/REST endpoints such as edge-attached cameras.
15
+
In Azure IoT Operations, the connector for REST/HTTP (preview) enables access to data from REST endpoints exposed by HTTP services.
@@ -21,9 +21,7 @@ In Azure IoT Operations, the connector for REST/HTTP (preview) enables access to
21
21
This article explains how to use the connector for REST/HTTP to perform tasks such as:
22
22
23
23
- Define the devices that connect HTTP sources to your Azure IoT Operations instance.
24
-
- Add assets, and define their streams, data points, and events to enable data flow from the HTTP source to the MQTT broker.
25
-
- Send an image snapshot to the MQTT broker.
26
-
- Save a video stream to a local file system.
24
+
- Add assets, and define the data points to enable the data flow from the HTTP source to the MQTT broker.
27
25
28
26
## Prerequisites
29
27
@@ -33,298 +31,57 @@ To configure devices and assets, you need a running instance of Azure IoT Operat
33
31
34
32
Your IT administrator must have configured the connector for REST/HTTP template for your Azure IoT Operations instance in the Azure portal.
35
33
36
-
A camera connected to your network and accessible from your Azure IoT Operations cluster. The camera must support the Real Time Streaming Protocol for video streaming. You also need the camera's username and password to authenticate with it.
34
+
You need any credentials required to access the HTTP source. If the HTTP source requires authentication, you need to create a Kubernetes secret that contains the username and password for the HTTP source.
37
35
38
36
## Deploy the connector for REST/HTTP
39
37
40
-
<!--TODO: Probably not necessary now we have the connector templates? -->
> If you don't enable preview features, you see the following error message in the `aio-supervisor-...` pod logs when you try to use the HTTP, media, or ONVIF connectors: `No connector configuration present for AssetEndpointProfile: <AssetEndpointProfileName>`.
46
42
47
43
## Create a device
48
44
49
-
To configure the connector for REST/HTTP, first create a device that defines the connection to the HTTP source. The device includes the URL of the HTTP source, the type of HTTP source, and any credentials you need to access the HTTP source.
50
-
51
-
If your HTTP endpoint requires authentication, create a secret in your Kubernetes cluster that stores the endpoint's username and password. The connector for REST/HTTP uses this secret to authenticate with the endpoint:
52
-
53
-
1. Create a YAML file called _contoso-http-secrets.yaml_ with the following content. Replace the placeholders with your camera's username and password encoded in base64:
54
-
55
-
```yaml
56
-
apiVersion: v1
57
-
kind: Secret
58
-
metadata:
59
-
name: contoso-http-secrets
60
-
type: Opaque
61
-
data:
62
-
username: "<YOUR HTTP USERNAME BASE64 ENCODED>"
63
-
password: "<YOUR HTTP PASSWORD BASE64 ENCODED>"
64
-
```
65
-
66
-
> [!TIP]
67
-
> To encode the username and password in base64 at a Bash prompt, use the following command: `echo -n "<STRING TO ENCODE>" | base64`.
68
-
69
-
1. To add the secret to your cluster in the default Azure IoT Operations namespace, run the following command:
:::image type="content" source="media/howto-use-http-connector/asset-endpoints.png" alt-text="Screenshot that shows the devices page in the operations experience." lightbox="media/howto-use-http-connector/asset-endpoints.png":::
82
-
83
-
> [!TIP]
84
-
> You can use the filter box to search for devices.
85
-
86
-
1. Enter the following endpoint information:
87
-
88
-
| Field | Value |
89
-
| --- | --- |
90
-
| Name | `opc-ua-connector-0` |
91
-
| Connector for OPC UA URL | `opc.tcp://opcplc-000000:50000` |
92
-
| User authentication | `Anonymous` |
93
-
94
-
1. To save the definition, select **Create**.
95
-
96
-
# [Azure CLI](#tab/cli)
97
-
98
-
Run the following command:
99
-
100
-
```azurecli
101
-
az iot ops device create opcua --name opc-ua-connector-0 --target-address opc.tcp://opcplc-000000:50000 -g {your resource group name} --instance {your instance name}
102
-
```
103
-
104
-
> [!TIP]
105
-
> Use `az connectedk8s list` to list the clusters you have access to.
106
-
107
-
To learn more, see [az iot ops device](/cli/azure/iot/ops/asset/endpoint).
The previous example configures the device to authenticate with the camera with a username and password. In the Bicep file, the authentication section of the device you created looks like the following example:
139
-
140
-
```bicep
141
-
authentication: {
142
-
method: 'UsernamePassword'
143
-
usernamePasswordCredentials: {
144
-
passwordSecretName: '${secretName}/password'
145
-
usernameSecretName: '${secretName}/username'
146
-
}
147
-
```
148
-
149
-
If your camera doesn't require a username and password, configure anonymous authentication as shown in the following example:
To configure the connector for REST/HTTP, first create a device that defines the connection to the HTTP source. The device includes the URL of the HTTP source and any credentials you need to access the HTTP source.
1. In the operations experience web UI, select **Devices** in the left navigation pane. Then select **Create new**.
174
48
175
-
# Find the name of your custom location
176
-
$CUSTOM_LOCATION_NAME = (az iot ops list -g $RESOURCE_GROUP --query "[0].extendedLocation.name" -o tsv)
49
+
1. Enter a name for your device, such as `http-connector`. To add the endpoint for the connector for REST/HTTP, select **New** on the **Microsoft.Http** tile.
177
50
178
-
# Use the Bicep file to deploy the device
179
-
az deployment group create --subscription $SUBSCRIPTION_ID --resource-group $RESOURCE_GROUP --template-file aep-media-connector.bicep --parameters targetAddress=$TARGET_ADDRESS customLocationName=$CUSTOM_LOCATION_NAME aepName=$AEP_NAME secretName=$SECRET_NAME
180
-
```
51
+
1. Add the details of the endpoint for the connector for REST/HTTP including any authentication credentials:
181
52
182
-
The following snippet shows the bicep file that you used to create the device:
53
+
:::image type="content" source="media/howto-use-http-connector/add-http-connector-endpoint.png" alt-text="Screenshot that shows how to add a connector for REST/HTTP endpoint" lightbox="media/howto-use-http-connector/add-http-connector-endpoint.png":::
The previous example configures the device to authenticate with the camera with a username and password. In the Bicep file, the authentication section of the device you created looks like the following example:
57
+
1. On the **Device details** page, select **Next** to continue.
187
58
188
-
```bicep
189
-
authentication: {
190
-
method: 'UsernamePassword'
191
-
usernamePasswordCredentials: {
192
-
passwordSecretName: '${secretName}/password'
193
-
usernameSecretName: '${secretName}/username'
194
-
}
195
-
```
59
+
1. On the **Add custom property** page, you can add any other properties you want to associate with the device. For example, you might add a property to indicate the manufacturer of the camera. Then select **Next** to continue
196
60
197
-
If your camera doesn't require a username and password, configure anonymous authentication as shown in the following example:
198
-
199
-
```bicep
200
-
authentication: {
201
-
method: 'Anonymous'
202
-
}
203
-
```
204
-
205
-
---
206
-
207
-
## Asset configuration
208
-
209
-
When you configure an asset, the `datasets.DataPoints` parameter specifies the action the connector for REST/HTTP takes on the asset. An HTTP asset supports the following task types:
210
-
211
-
| Task type | Description |
212
-
|-----------|-------------|
213
-
| `snapshot-to-mqtt` | Capture snapshots from a camera and publishes them to an MQTT topic. |
214
-
| `snapshot-to-fs` | Capture snapshots from a camera and saves them to the local file system. |
215
-
216
-
The following examples show how to deploy assets for each task type.
217
-
218
-
> [!TIP]
219
-
> The HTTP pods aren't created in Kubernetes until you deploy an asset that uses the connector for REST/HTTP. If you try to run the `kubectl get pods` command before deploying an asset, you see no HTTP pods.
220
-
221
-
## Snapshot to MQTT
222
-
223
-
To configure an asset that captures snapshots from an endpoint and publishes them to an MQTT topic:
224
-
225
-
# [Operations experience](#tab/portal)
226
-
227
-
Go to the operations experience web UI and select **Assets**. Then select **Create asset**.
228
-
229
-
Add the configuration for a snapshot to mqtt asset.
230
-
231
-
<!-- TODO: Expand this section when we have the UI available -->
232
-
233
-
# [Azure CLI](#tab/cli)
234
-
235
-
Use the `az iot ops asset create` command to create a snapshot to mqtt asset.
236
-
237
-
<!-- TODO: Expand this section when we have the CLI available -->
1. On the **Summary** page, review the details of the device and select **Create** to create the asset.
294
62
295
-
To verify that snapshots are publishing to the MQTT broker, use the **mosquitto_sub** tool. In this example, you run the **mosquitto_sub** tool inside a pod in your Kubernetes cluster:
63
+
1. After the device is created, you can view it in the **Devices**list:
296
64
297
-
1. Run the following command to deploy a pod that includes the **mosquitto_pub** and **mosquitto_sub** tools that are useful for interacting with the MQTT broker in the cluster:
65
+
:::image type="content" source="media/howto-use-http-connector/http-connector-device-created.png" alt-text="Screenshot that shows the list of devices." lightbox="media/howto-use-http-connector/http-connector-device-created.png":::
> This configuration isn't secure. Don't use this configuration in a production environment.
69
+
To define a namespace asset that publishes data points from the HTTP endpoint, follow these steps:
305
70
306
-
1. When the **mqtt-client** pod is running, run the following command to create a shell environment in the pod you created:
71
+
1.In the operations experience web UI, select **Assets** in the left navigation pane. Then select **Create namespace asset**.
307
72
308
-
```console
309
-
kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh
310
-
```
73
+
1. Select the inbound endpoint for the connector for REST/HTTP that you created in the previous section.
311
74
312
-
1. At the Bash shell in the **mqtt-client** pod, run the following command to connect to the MQTT broker using the **mosquitto_sub** tool subscribed to the `azure-iot-operations/data` topic:
75
+
1.Enter a name for your asset, such as `my-http-source`.
1. Add any custom properties you want to associate with the asset. For example, you might add a property to indicate the manufacturer of the camera. Select **Next** to continue.
317
78
318
-
This command captures the raw payload from a single message and saves it to a file called **image.jpeg** in the pod's filing system. To exit the pod's shell environment, type `exit`.
79
+
1. On the **Data points** page, select **Add data point**to add a data point for the asset. For example:
319
80
320
-
1. To copy the image file from the pod to your local machine, run the following command:
81
+
:::image type="content" source="media/howto-use-http-connector/add-data-point.png" alt-text="Screenshot that shows how to add a data point for HTTP source." lightbox="media/howto-use-http-connector/add-data-point.png":::
Add details for each data point to publish to the MQTT broker. Then select **Next** to continue.
325
84
326
-
When you finish testing the asset, you can delete it by running the following command:
85
+
1. On the **Review** page, review the details of the asset and select **Create** to create the asset. After a few minutes, the asset is listed on the **Assets** page:
327
86
328
-
```console
329
-
az iot ops asset delete -n asset-snapshot-to-mqtt -g $RESOURCE_GROUP
330
-
```
87
+
:::image type="content" source="media/howto-use-http-connector/http-asset-created.png" alt-text="Screenshot that shows the list of assets." lightbox="media/howto-use-http-connector/http-asset-created.png":::
0 commit comments