Skip to content

Commit 6d78bc3

Browse files
ShannonLeavittShannonLeavitt
authored
Merge pull request #177379 from v-krishnag/restdata
rest api data export
2 parents 32e0507 + 11e8a95 commit 6d78bc3

File tree

4 files changed

+360
-2
lines changed

4 files changed

+360
-2
lines changed

‎articles/iot-central/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,8 @@
196196
href: core/howto-query-with-rest-api.md
197197
- name: Manage users and roles
198198
href: core/howto-manage-users-roles-with-rest-api.md
199+
- name: Data export
200+
href: core/howto-manage-data-export-with-rest-api.md
199201
- name: Manage device templates
200202
href: core/howto-manage-device-templates-with-rest-api.md
201203
- name: Control devices

‎articles/iot-central/core/howto-manage-data-export-with-rest-api.md

Lines changed: 356 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,356 @@
1+
---
2+
title: Use the REST API to manage data export in Azure IoT Central
3+
description: How to use the IoT Central REST API to manage data export in an application
4+
author: v-krishnag
5+
ms.author: v-krishnag
6+
ms.date: 10/18/2021
7+
ms.topic: how-to
8+
ms.service: iot-central
9+
services: iot-central
10+
11+
---
12+
13+
# How to use the IoT Central REST API to manage data exports
14+
15+
The IoT Central REST API lets you develop client applications that integrate with IoT Central applications. You can use the REST API to create and manage [data exports](howto-export-data.md) in your IoT Central application.
16+
17+
Every IoT Central REST API call requires an authorization header. To learn more, see [How to authenticate and authorize IoT Central REST API calls](howto-authorize-rest-api.md).
18+
19+
For the reference documentation for the IoT Central REST API, see [Azure IoT Central REST API reference](/rest/api/iotcentral/).
20+
21+
## Data export
22+
23+
You can use the IoT Central data export feature to stream telemetry, property changes, device connectivity events, device lifecycle events, and device template lifecycle events to destinations such as Azure Event Hubs, Azure Service Bus, Azure Blob Storage, and webhook endpoints.
24+
25+
Each data export definition can send data to one or more destinations. Create the destination definitions before you create the export definition.
26+
27+
### Create or update a destination
28+
29+
Use the following request to create or update a destination definition:
30+
31+
```http
32+
PUT https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.0
33+
```
34+
35+
* destinationId - Unique ID for the destination.
36+
37+
The following example shows a request body that creates a blob storage destination:
38+
39+
```json
40+
{
41+
"displayName": "Blob Storage Destination",
42+
"type": "blobstorage@v1",
43+
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
44+
"containerName": "central-data"
45+
}
46+
```
47+
48+
The request body has some required fields:
49+
50+
* `displayName`: Display name of the destination.
51+
* `type`: Type of destination object which can be one of: `blobstorage@v1`, `dataexplorer@v1`, `eventhubs@v1`, `servicebusqueue@v1`, `servicebustopic@v1`, `webhook@v1`.
52+
* `connectionString`:The connection string for accessing the destination resource.
53+
* `containerName`: For a blob storage destination, the name of the container where data should be written.
54+
55+
The response to this request looks like the following example:
56+
57+
```json
58+
{
59+
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
60+
"displayName": "Blob Storage Destination",
61+
"type": "blobstorage@v1",
62+
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
63+
"containerName": "central-data",
64+
"status": "waiting"
65+
}
66+
```
67+
68+
### Get a destination by ID
69+
70+
Use the following request to retrieve details of a destination from your application:
71+
72+
```http
73+
GET https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.0
74+
```
75+
76+
The response to this request looks like the following example:
77+
78+
```json
79+
{
80+
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
81+
"displayName": "Blob Storage Destination",
82+
"type": "blobstorage@v1",
83+
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
84+
"containerName": "central-data",
85+
"status": "waiting"
86+
}
87+
```
88+
89+
### List destinations
90+
91+
Use the following request to retrieve a list of destinations from your application:
92+
93+
```http
94+
GET https://{subdomain}.{baseDomain}/api/dataExport/destinations?api-version=1.0
95+
```
96+
97+
The response to this request looks like the following example:
98+
99+
```json
100+
{
101+
"value": [
102+
{
103+
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
104+
"displayName": "Blob Storage Destination",
105+
"type": "blobstorage@v1",
106+
"authorization": {
107+
"type": "connectionString",
108+
"connectionString": DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
109+
"containerName": "central-data"
110+
},
111+
"status": "waiting"
112+
},
113+
{
114+
"id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
115+
"displayName": "Webhook destination",
116+
"type": "webhook@v1",
117+
"url": "http://requestbin.net/r/f7x2i1ug",
118+
"headerCustomizations": {},
119+
"status": "error",
120+
}
121+
}
122+
]
123+
}
124+
```
125+
126+
### Patch a destination
127+
128+
```http
129+
PATCH https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.0
130+
```
131+
132+
You can use this to perform an incremental update to an export. The sample request body looks like the following example which updates the `displayName` to a destination:
133+
134+
```json
135+
{
136+
"displayName": "Blob Storage",
137+
"type": "blobstorage@v1",
138+
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
139+
"containerName": "central-data"
140+
}
141+
```
142+
143+
The response to this request looks like the following example:
144+
145+
```json
146+
{
147+
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
148+
"displayName": "Blob Storage",
149+
"type": "blobstorage@v1",
150+
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
151+
"containerName": "central-data",
152+
"status": "waiting"
153+
}
154+
```
155+
156+
### Delete a destination
157+
158+
Use the following request to delete a destination:
159+
160+
```http
161+
DELETE https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.0
162+
```
163+
164+
### Create or update an export definition
165+
166+
Use the following request to create or update a data export definition:
167+
168+
```http
169+
PUT https://{subdomain}.{baseDomain}/api/dataExport/exports/{exportId}?api-version=1.0
170+
```
171+
172+
The following example shows a request body that creates an export definition for device telemetry:
173+
174+
```json
175+
{
176+
"displayName": "Enriched Export",
177+
"enabled": true,
178+
"source": "telemetry",
179+
"enrichments": {
180+
"Custom data": {
181+
"value": "My value"
182+
}
183+
},
184+
"destinations": [
185+
{
186+
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
187+
}
188+
]
189+
}
190+
```
191+
192+
The request body has some required fields:
193+
194+
* `displayName`: Display name of the export.
195+
* `enabled`: Toggle to start/stop an export from sending data.
196+
* `source`: The type of data to export.
197+
* `destinations`: The list of destinations to which the export should send data. The destination IDs must already exist in the application.
198+
199+
There are some optional fields you can use to add more details to the export.
200+
201+
* `enrichments`: Additional pieces of information to include with each sent message. Data is represented as a set of key/value pairs, where the key is the name of the enrichment that will appear in the output message and the value identifies the data to send.
202+
* `filter`: Query defining which events from the source should be exported.
203+
204+
The response to this request looks like the following example:
205+
206+
```json
207+
{
208+
"id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
209+
"displayName": "Enriched Export",
210+
"enabled": true,
211+
"source": "telemetry",
212+
"enrichments": {
213+
"Custom data": {
214+
"value": "My value"
215+
}
216+
},
217+
"destinations": [
218+
{
219+
"id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
220+
}
221+
],
222+
"status": "starting"
223+
}
224+
```
225+
226+
### Get an export by ID
227+
228+
Use the following request to retrieve details of an export definition from your application:
229+
230+
```http
231+
GET https://{subdomain}.{baseDomain}/api/dataExport/exports/{exportId}?api-version=1.0
232+
```
233+
234+
The response to this request looks like the following example:
235+
236+
```json
237+
{
238+
"id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
239+
"displayName": "Blob Storage Destination",
240+
"type": "blobstorage@v1",
241+
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
242+
"containerName": "central-data",
243+
"status": "waiting"
244+
}
245+
```
246+
247+
### List export definitions
248+
249+
Use the following request to retrieve a list of export definitions from your application:
250+
251+
```http
252+
GET https://{subdomain}.{baseDomain}/api/dataExport/exports?api-version=1.0
253+
```
254+
255+
The response to this request looks like the following example:
256+
257+
```json
258+
{
259+
"value": [
260+
{
261+
"id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
262+
"displayName": "Enriched Export",
263+
"enabled": true,
264+
"source": "telemetry",
265+
"enrichments": {
266+
"Custom data": {
267+
"value": "My value"
268+
}
269+
},
270+
"destinations": [
271+
{
272+
"id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
273+
}
274+
],
275+
"status": "starting"
276+
},
277+
{
278+
"id": "802894c4-33bc-4f1e-ad64-e886f315cece",
279+
"displayName": "Enriched Export",
280+
"enabled": true,
281+
"source": "telemetry",
282+
"enrichments": {
283+
"Custom data": {
284+
"value": "My value"
285+
}
286+
},
287+
"destinations": [
288+
{
289+
"id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
290+
}
291+
],
292+
"status": "healthy"
293+
}
294+
]
295+
}
296+
```
297+
298+
### Patch an export definition
299+
300+
```http
301+
PATCH https://{subdomain}.{baseDomain}/dataExport/exports/{exportId}?api-version=1.0
302+
```
303+
304+
You can use this to perform an incremental update to an export. The sample request body looks like the following example which updates the `enrichments` to an export:
305+
306+
```json
307+
{
308+
"displayName": "Enriched Export",
309+
"enabled": true,
310+
"source": "telemetry",
311+
"enrichments": {
312+
"Custom data": {
313+
"value": "My value 2"
314+
}
315+
},
316+
"destinations": [
317+
{
318+
"id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
319+
}
320+
]
321+
}
322+
```
323+
324+
The response to this request looks like the following example:
325+
326+
```json
327+
{
328+
"id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
329+
"displayName": "Enriched Export",
330+
"enabled": true,
331+
"source": "telemetry",
332+
"enrichments": {
333+
"Custom data": {
334+
"value": "My"
335+
}
336+
},
337+
"destinations": [
338+
{
339+
"id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
340+
}
341+
],
342+
"status": "healthy"
343+
}
344+
```
345+
346+
### Delete an export definition
347+
348+
Use the following request to delete an export definition:
349+
350+
```http
351+
DELETE https://{subdomain}.{baseDomain}/api/dataExport/destinations/{destinationId}?api-version=1.0
352+
```
353+
354+
## Next steps
355+
356+
Now that you've learned how to manage data export with the REST API, a suggested next step is to [How to use the IoT Central REST API to manage device templates](howto-manage-device-templates-with-rest-api.md).

‎articles/iot-central/core/howto-manage-device-templates-with-rest-api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Use the REST API to add device templates in Azure IoT Central
33
description: How to use the IoT Central REST API to add device templates in an application
44
author: v-krishnag
55
ms.author: v-krishnag
6-
ms.date: 09/28/2020
6+
ms.date: 09/28/2021
77
ms.topic: how-to
88
ms.service: iot-central
99
services: iot-central

‎articles/iot-central/core/howto-manage-users-roles-with-rest-api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -229,4 +229,4 @@ DELETE https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-v
229229

230230
## Next steps
231231

232-
Now that you've learned how to manage users and roles with the REST API, a suggested next step is to [How to use the IoT Central REST API to manage device templates](howto-manage-device-templates-with-rest-api.md).
232+
Now that you've learned how to manage users and roles with the REST API, a suggested next step is to [How to use the IoT Central REST API to manage data exports.](howto-manage-data-export-with-rest-api.md)

0 commit comments

Comments
 (0)