Skip to content

Commit 3efec2d

Browse files
v-krishnagv-krishnag
committed
rest api data export
1 parent 8d43c41 commit 3efec2d

File tree

2 files changed

+356
-0
lines changed

2 files changed

+356
-0
lines changed

‎articles/iot-central/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,8 @@
192192
href: core/howto-authorize-rest-api.md
193193
- name: Manage users and roles
194194
href: core/howto-manage-users-roles-with-rest-api.md
195+
- name: Data export
196+
href: core/howto-manage-data-export-with-rest-api.md
195197
- name: Control devices
196198
href: core/howto-control-devices-with-rest-api.md
197199
- name: Manage jobs

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

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

0 commit comments

Comments
 (0)