Skip to content

Commit 570f409

Browse files
uhabiba04uhabiba04
committed
updating as per the microsoft documenation standards
1 parent 7ca1e9b commit 570f409

File tree

2 files changed

+90
-82
lines changed

2 files changed

+90
-82
lines changed

‎articles/industry/agriculture/ingest-historical-telemetry-data-in-azure-farmbeats.md

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Ingesting historical data from Internet of Things (IoT) resources such as device
1515

1616
## Before you begin
1717

18-
Before you proceed with this article, make sure that you've installed FarmBeats and collected historical data from your IoT devices. You also need to enable partner access as mentioned in the following steps.
18+
Before you proceed with this article, ensure that you've installed FarmBeats and collected historical data from your IoT devices. You also need to enable partner access as mentioned in the following steps.
1919

2020
## Enable partner access
2121

@@ -29,10 +29,11 @@ You need to enable partner integration to your Azure FarmBeats instance. This st
2929

3030
Follow these steps:
3131

32-
>[!NOTE]
32+
> [!NOTE]
3333
> You must be an administrator to do the following steps.
3434
3535
1. Download the [zip file](https://aka.ms/farmbeatspartnerscriptv2), and extract it to your local drive. There will be one file inside the zip file.
36+
3637
2. Sign in to https://portal.azure.com/ and go to **Azure Active Directory** > **App Registrations**.
3738

3839
3. Select the **App Registration** that was created as part of your FarmBeats deployment. It will have the same name as your FarmBeats Datahub.
@@ -62,9 +63,10 @@ Follow these steps:
6263
```
6364
6465
10. Follow the onscreen instructions to capture the values for **API Endpoint**, **Tenant ID**, **Client ID**, **Client Secret**, and **EventHub Connection String**.
66+
6567
## Create device or sensor metadata
6668
67-
Now that you have the required credentials, you can define the device and sensors. To do this, create the metadata by calling FarmBeats APIs. Make sure to call the APIs as the client app that you created in the above section.
69+
Now that you have the required credentials, you can define the device and sensors. To do this, create the metadata by calling FarmBeats APIs. Make sure to call the APIs as the client app that you have created in the above section.
6870
6971
FarmBeats Datahub has the following APIs that enable creation and management of device or sensor metadata.
7072
@@ -105,17 +107,17 @@ Follow these steps:
105107
| SensorMeasures > Unit | Unit of sensor telemetry data. The system-defined units are NoUnit, Celsius, Fahrenheit, Kelvin, Rankine, Pascal, Mercury, PSI, MilliMeter, CentiMeter, Meter, Inch, Feet, Mile, KiloMeter, MilesPerHour, MilesPerSecond, KMPerHour, KMPerSecond, MetersPerHour, MetersPerSecond, Degree, WattsPerSquareMeter, KiloWattsPerSquareMeter, MilliWattsPerSquareCentiMeter, MilliJoulesPerSquareCentiMeter, VolumetricWaterContent, Percentage, PartsPerMillion, MicroMol, MicroMolesPerLiter, SiemensPerSquareMeterPerMole, MilliSiemensPerCentiMeter, Centibar, DeciSiemensPerMeter, KiloPascal, VolumetricIonContent, Liter, MilliLiter, Seconds, UnixTimestamp, MicroMolPerMeterSquaredPerSecond, InchesPerHour To add more, refer to the /ExtendedType API.|
106108
| SensorMeasures > AggregationType | Values can be none, average, maximum, minimum, or StandardDeviation. |
107109
| Name | Name to identify a resource. For example, the model name or product name. |
108-
| Description | Provide a meaningful description of the model. |
109-
| Properties | Additional properties from the manufacturer. |
110+
| Description | Provide a meaningful description of the model.|
111+
| Properties | Additional properties from the manufacturer.|
110112
| **Sensor** | |
111-
| HardwareId | Unique ID for the sensor set by the manufacturer. |
112-
| SensorModelId | ID of the associated sensor model. |
113+
| HardwareId | Unique ID for the sensor set by the manufacturer.|
114+
| SensorModelId | ID of the associated sensor model.|
113115
| Location | Sensor latitude (-90 to +90), longitude (-180 to 180), and elevation (in meters).|
114-
| Port > Name | Name and type of the port that the sensor is connected to on the device. This needs to be the same name as defined in the device model. |
115-
| DeviceID | ID of the device that the sensor is connected to. |
116+
| Port > Name | Name and type of the port that the sensor is connected to on the device. This needs to be the same name as defined in the device model.|
117+
| DeviceID | ID of the device that the sensor is connected to. |
116118
| Name | Name to identify resource. For example, sensor name or product name and model number or product code.|
117-
| Description | Provide a meaningful description. |
118-
| Properties |Additional properties from the manufacturer. |
119+
| Description | Provide a meaningful description.|
120+
| Properties |Additional properties from the manufacturer.|
119121
120122
For more information about objects, see [Swagger](https://aka.ms/FarmBeatsDatahubSwagger).
121123
@@ -158,7 +160,6 @@ token_response = context.acquire_token_with_client_credentials(ENDPOINT, CLI
158160
access_token = token_response.get('accessToken') 
159161
```
160162

161-
162163
**HTTP request headers**
163164

164165
Here are the most common request headers that must be specified when you make an API call to FarmBeats Datahub:
@@ -271,6 +272,7 @@ Sensor
271272
}
272273
}
273274
```
275+
274276
The following sample request creates a device. This request has input JSON as payload with the request body.
275277

276278
```bash
@@ -288,6 +290,7 @@ import requests
288290
import json
289291

290292
# Got access token - Calling the Device Model API
293+
291294
headers = {
292295
"Authorization": "Bearer " + access_token,
293296
"Content-Type" : "application/json"
@@ -296,7 +299,6 @@ payload = '{"type" : "Node", "productCode" : "TestCode", "ports": [{"name": "por
296299
response = requests.post(ENDPOINT + "/DeviceModel", data=payload, headers=headers)
297300
```
298301

299-
300302
> [!NOTE]
301303
> The APIs return unique IDs for each instance created. You must retain the IDs to send the corresponding telemetry messages.
302304
@@ -434,7 +436,6 @@ Here's an example of a telemetry message:
434436
}
435437
```
436438

437-
438439
## Next steps
439440

440441
For more information about REST API-based integration details, see [REST API](rest-api-in-azure-farmbeats.md).

‎articles/industry/agriculture/query-telemetry-data-from-azure-farmbeats.md

Lines changed: 75 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -11,102 +11,109 @@ ms.author: sunasing
1111

1212
This article describes how to query ingested sensor data from Azure FarmBeats.
1313

14-
Ingesting data from Internet of Things (IoT) resources such as devices and sensors is a common scenario in FarmBeats. You create metadata for devices and sensors and then ingest the historical data to FarmBeats in a canonical format. Once the sensor data is available on FarmBeats Data hub, we can query the same to generate actionable insights or build models.
14+
Ingesting data from Internet of Things (IoT) resources such as devices and sensors is a common scenario in FarmBeats. You create metadata for devices and sensors and then ingest the historical data to FarmBeats in a canonical format. Once the sensor data is available on FarmBeats Datahub, we can query the same to generate actionable insights or build models.
1515

1616
## Before you begin
1717

18-
Before you proceed with this article, make sure that you've installed FarmBeats and ingested sensor telemetry data from your IoT devices to FarmBeats.
18+
Before you proceed with this article, ensure that you've installed FarmBeats and ingested sensor telemetry data from your IoT devices to FarmBeats.
19+
1920
To ingest sensor telemetry data, visit [ingest historical telemetry data](ingest-historical-telemetry-data-in-azure-farmbeats.md)
2021

21-
Before you proceed, also make sure you are familiar with FarmBeats REST APIs as you will query ingested telemetry using APIs. For more details on FarmBeats APIs, please see [FarmBeats REST APIs](rest-api-in-azure-farmbeats.md). **Ensure that you are able to make API requests to your FarmBeats Data hub endpoint**
22+
Before you proceed, you also need to ensure you are familiar with FarmBeats REST APIs as you will query ingested telemetry using the APIs. For more details on FarmBeats APIs, see [FarmBeats REST APIs](rest-api-in-azure-farmbeats.md). **Ensure that you are able to make API requests to your FarmBeats Datahub endpoint**.
2223

2324
## Query ingested sensor telemetry data
2425

25-
There are two ways to access and query telemetry data from FarmBeats: API and Time Series Insights (TSI).
26+
There are two ways to access and query telemetry data from FarmBeats:
27+
28+
- API and
29+
- Time Series Insights (TSI).
2630

2731
### Query using REST API
2832

29-
Follow the below steps to query the ingested sensor telemetry data using FarmBeats REST APIs:
33+
Follow the steps to query the ingested sensor telemetry data using FarmBeats REST APIs:
34+
35+
1. Identify the sensor you are interested in. You can do this by making a GET request on /Sensor API.
3036

31-
1. Identify the sensor you are interested in. You can do this by making a GET request on /Sensor API. Note the **id** and the **sensorModelId** of the interested sensor object.
37+
> [!NOTE]
38+
> The **id** and the **sensorModelId** of the interested sensor object.
3239
33-
2. Make a GET/{id} on /SensorModel API for the **sensorModelId** as noted in step 1. The "Sensor Model" has all the metadata and details about the ingested telemetry from the sensor. For example, "Sensor Measure" within the "Sensor Model" object has details about what measures is the sensor sending and in what types and units. For example,
40+
2. Make a GET/{id} on /SensorModel API for the **ensorModelId** as noted in step 1. The "Sensor Model" has all the metadata and details about the ingested telemetry from the sensor. For example, **Sensor Measure** within the **Sensor Model** object has details about what measures is the sensor sending and in what types and units. For example,
3441

35-
```json
36-
{
37-
"name": "moist_soil_last <name of the sensor measure - this is what we will receive as part of the queried telemetry data>",
38-
"dataType": "Double <Data Type - eg. Double>",
39-
"type": "SoilMoisture <Type of measure eg. temperature, soil moisture etc.>",
40-
"unit": "Percentage <Unit of measure eg. Celsius, Percentage etc.>",
41-
"aggregationType": "None <either of None, Average, Maximum, Minimum, StandardDeviation>",
42-
"description": "<Description of the measure>"
43-
}
44-
```
42+
```json
43+
{
44+
"name": "moist_soil_last <name of the sensor measure - this is what we will receive as part of the queried telemetry data>",
45+
"dataType": "Double <Data Type - eg. Double>",
46+
"type": "SoilMoisture <Type of measure eg. temperature, soil moisture etc.>",
47+
"unit": "Percentage <Unit of measure eg. Celsius, Percentage etc.>",
48+
"aggregationType": "None <either of None, Average, Maximum, Minimum, StandardDeviation>",
49+
"description": "<Description of the measure>"
50+
}
51+
```
4552
Make a note of the response from the GET/{id} call for the Sensor Model.
4653

4754
3. Do a POST call on /Telemetry API with the following input payload
4855

49-
```json
50-
{
51-
"sensorId": "<id of the sensor as noted in step 1>",
52-
"searchSpan": {
53-
"from": "<desired start timestamp in ISO 8601 format; default is UTC>",
54-
"to": "<desired end timestamp in ISO 8601 format; default is UTC>"
55-
},
56-
"filter": {
57-
"tsx": "string"
58-
},
59-
"projectedProperties": [
60-
{
61-
"additionalProp1": "string",
62-
"additionalProp2": "string",
63-
"additionalProp3": "string"
64-
}
65-
]
66-
}
67-
```
56+
```json
57+
{
58+
"sensorId": "<id of the sensor as noted in step 1>",
59+
"searchSpan": {
60+
"from": "<desired start timestamp in ISO 8601 format; default is UTC>",
61+
"to": "<desired end timestamp in ISO 8601 format; default is UTC>"
62+
},
63+
"filter": {
64+
"tsx": "string"
65+
},
66+
"projectedProperties": [
67+
{
68+
"additionalProp1": "string",
69+
"additionalProp2": "string",
70+
"additionalProp3": "string"
71+
}
72+
]
73+
}
74+
```
6875
4. The response from the /Telemetry API will look something like this:
6976

70-
```json
71-
{
72-
"timestamps": [
73-
"2020-XX-XXT07:30:00Z",
74-
"2020-XX-XXT07:45:00Z"
75-
],
76-
"properties": [
77-
{
78-
"values": [
79-
"<id of the sensor>",
80-
"<id of the sensor>"
81-
],
82-
"name": "Id",
83-
"type": "String"
84-
},
85-
{
86-
"values": [
87-
2.1,
88-
2.2
89-
],
90-
"name": "moist_soil_last <name of the SensorMeasure as defined in the SensorModel object>",
91-
"type": "Double <Data Type of the value - eg. Double>"
92-
}
93-
]
94-
}
95-
```
77+
```json
78+
{
79+
"timestamps": [
80+
"2020-XX-XXT07:30:00Z",
81+
"2020-XX-XXT07:45:00Z"
82+
],
83+
"properties": [
84+
{
85+
"values": [
86+
"<id of the sensor>",
87+
"<id of the sensor>"
88+
],
89+
"name": "Id",
90+
"type": "String"
91+
},
92+
{
93+
"values": [
94+
2.1,
95+
2.2
96+
],
97+
"name": "moist_soil_last <name of the SensorMeasure as defined in the SensorModel object>",
98+
"type": "Double <Data Type of the value - eg. Double>"
99+
}
100+
]
101+
}
102+
```
96103
In the above example response, the queried sensor telemetry gives data for two timestamps along with the measure name ("moist_soil_last") and values of the reported telemetry in the two timestamps. You will need to refer to the associated Sensor Model (as described in step 2) to interpret the type and unit of the reported values.
97104

98105
### Query using Azure Time Series Insights (TSI)
99106

100-
FarmBeats leverages [Azure Time Series Insights (TSI)](https://azure.microsoft.com/services/time-series-insights/) to ingest, store, query and visualize data at Internet of Things (IoT) scale--data that's highly contextualized and optimized for time series.
107+
FarmBeats leverages [Azure Time Series Insights (TSI)](https://azure.microsoft.com/services/time-series-insights/) to ingest, store, query and visualize data at IoT scale--data that's highly contextualized and optimized for time series.
101108

102-
Telemetry data is received on an EventHub and then processed and pushed to a TSI environment within FarmBeats resource group. Data can then be directly queried from the TSI. For more information, refer [TSI documentation](https://docs.microsoft.com/azure/time-series-insights/time-series-insights-explorer)
109+
Telemetry data is received on an EventHub and then processed and pushed to a TSI environment within FarmBeats resource group. Data can then be directly queried from the TSI. For more information, see [TSI documentation](https://docs.microsoft.com/azure/time-series-insights/time-series-insights-explorer)
103110

104-
Follow the below steps to visualize data on TSI
111+
Follow the steps to visualize data on TSI:
105112

106-
1. Go to Azure Portal -> FarmBeats DataHub resource group -> Select Time Series Insights environment (tsi-xxxx) -> Data Access Policies. Add user with Reader or Contributor access.
107-
2. Go to the Overview page of Time Series Insights environment (tsi-xxxx) and Select the “Time Series Insights Explorer URL”. You will now be able to visualize the ingested telemetry.
113+
1. Go to **Azure Portal** > **FarmBeats DataHub resource group** > select **Time Series Insights** environment (tsi-xxxx) > **Data Access Policies**. Add user with Reader or Contributor access.
114+
2. Go to the **Overview** page of **Time Series Insights** environment (tsi-xxxx) and select the **Time Series Insights Explorer URL**. You'll now be able to visualize the ingested telemetry.
108115

109-
Apart from storing, querying and visualization of telemetry, TSI also enables integration to a Power BI dashboard. More details [here]( https://docs.microsoft.com/azure/time-series-insights/how-to-connect-power-bi)
116+
Apart from storing, querying and visualization of telemetry, TSI also enables integration to a Power BI dashboard. For more information [see here]( https://docs.microsoft.com/azure/time-series-insights/how-to-connect-power-bi)
110117

111118
## Next steps
112119

0 commit comments

Comments
 (0)