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
The Azure FarmBeats APIs provide agricultural businesses with a standardized RESTful interface with JSON-based responses to help you take advantage of Azure FarmBeats capabilities, such as:
17
-
18
-
- APIs to get sensor, camera, drone, weather, satellite, and curated ground data.
19
-
- Normalization and contextualization of data across common data providers.
20
-
- Schematized access and query capabilities on all ingested data.
21
-
- Automatic generation of metadata that can be queried, based on agronomic features.
22
-
- Automatically generated time sequence aggregates for rapid model building.
23
-
- Integrated Azure Data Factory engine to easily build custom data processing pipelines.
24
-
25
-
## Application development
26
-
27
-
The FarmBeats APIs contain Swagger technical documentation. For information on all the APIs and their corresponding requests or responses, see [Swagger](https://aka.ms/FarmBeatsDatahubSwagger).
28
-
29
-
The following table summarizes all the objects and resources in FarmBeats Datahub.
30
-
31
-
| Objects and resources | Description
32
-
--- | ---|
33
-
Farm | Farm corresponds to a physical location of interest within the FarmBeats system. Each farm has a farm name and a unique farm ID. |
34
-
Device | Device corresponds to a physical device present on the farm. Each device has a unique device ID. A device is typically provisioned to a farm with a farm ID.
35
-
DeviceModel | DeviceModel corresponds to the metadata of the device, such as the manufacturer and the type of device, which is either gateway or node.
36
-
Sensor | Sensor corresponds to a physical sensor that records values. A sensor is typically connected to a device with a device ID.
37
-
SensorModel | SensorModel corresponds to the metadata of the sensor, such as the manufacturer, the type of sensor, which is either analog or digital, and the sensor measurement, such as ambient temperature and pressure.
38
-
Telemetry | Telemetry provides the ability to read telemetry messages for a particular sensor and time range.
39
-
Job | Job corresponds to any workflow of activities that are executed in the FarmBeats system to get a desired output. Each job is associated with a job ID and job type.
40
-
JobType | JobType corresponds to different job types supported by the system. System-defined and user-defined job types are included.
41
-
ExtendedType | ExtendedType corresponds to the list of system- and user-defined types in the system. ExtendedType helps set up a new sensor, scene, or scene file type in the FarmBeats system.
42
-
Partner | Partner corresponds to the sensor and imagery integration partner for FarmBeats.
43
-
Scene | Scene corresponds to any generated output in the context of a farm. Each scene has a scene ID, scene source, scene type, and farm ID associated with it. Each scene ID can have multiple scene files associated with it.
44
-
SceneFile |SceneFile corresponds to all the files that are generated for a single scene. A single scene ID can have multiple SceneFile IDs associated with it.
45
-
Rule |Rule corresponds to a condition for farm-related data to trigger an alert. Each rule is in the context of a farm's data.
46
-
Alert | Alert corresponds to a notification, which gets generated when a rule condition is met. Each alert is in the context of a rule.
47
-
RoleDefinition | RoleDefinition defines allowed and disallowed actions for a role.
48
-
RoleAssignment |RoleAssignment corresponds to the assignment of a role to a user or a service principal.
49
-
50
-
### Data format
51
-
52
-
JSON is a common language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see the [JSON website](https://www.json.org/).
53
-
54
-
## Authentication and authorization
55
-
56
-
HTTP requests to the REST API are protected with Azure Active Directory (Azure AD).
57
-
To make an authenticated request to the REST APIs, client code requires authentication with valid credentials before you can call the API. Authentication is coordinated between the various actors by Azure AD. It provides your client with an access token as proof of the authentication. The token is then sent in the HTTP Authorization header of REST API requests. To learn more about Azure AD authentication, see [Azure Active Directory](https://portal.azure.com) for developers.
58
-
59
-
The access token must be sent in subsequent API requests, in the header section, as:
Here are the most common request headers that you must specify when you make an API call to Azure FarmBeats Datahub.
68
-
69
-
70
-
**Header** | **Description and example**
71
-
--- | ---
72
-
Content-Type | The request format (Content-Type: application/<format>). For Azure FarmBeats Datahub APIs, the format is JSON. Content-Type: application/json
73
-
Authorization | Specifies the access token required to make an API call. Authorization: Bearer <Access-Token>
74
-
Accept | The response format. For Azure FarmBeats Datahub APIs, the format is JSON. Accept: application/json
75
-
76
-
### API requests
77
-
78
-
To make a REST API request, you combine the HTTP (GET, POST, PUT, or DELETE) method, the URL to the API service, the URI to a resource to query, submit data to, update, or delete, and then add one or more HTTP request headers.
79
-
80
-
The URL to the API service is your Datahub URL, for example, https://\<yourdatahub-website-name>.azurewebsites.net.
81
-
82
-
Optionally, you can include query parameters on GET calls to filter, limit the size of, and sort the data in the responses.
83
-
84
-
The following sample request is used to get the list of devices:
For REST GET calls, you can filter, limit the size of, and sort the data in an API response by including one or more query parameters on the request URI. For the query parameters, see the API documentation and the individual GET calls.
101
-
For example, when you query the list of devices (GET call on /Device), the following query parameters can be specified:
102
-
103
-
104
-
105
-
### Error handling
106
-
107
-
Azure FarmBeats Datahub APIs return the standard HTTP errors. The most common error codes are as follows:
108
-
109
-
|Error code | Description |
110
-
|--- | --- |
111
-
|200 | Success |
112
-
|201 | Create (Post) Success |
113
-
|400 | Bad Request. There is an error in the request. |
114
-
|401 | Unauthorized. The caller of the API is not authorized to access the resource. |
115
-
|404 | Resource Not Found |
116
-
|5XX | Internal Server error. The error codes starting with 5XX means there is some error on the server. Refer to server logs and the following section for more details. |
117
-
118
-
119
-
In addition to the standard HTTP errors, Azure FarmBeats Datahub APIs also return internal errors in the following format:
120
-
121
-
```json
122
-
{
123
-
"message": "<More information on the error>",
124
-
"status": "<error code>”,
125
-
"code": "<InternalErrorCode>",
126
-
"moreInfo": "<Details of the error>"
127
-
}
128
-
```
129
-
130
-
In this example, when a farm was created, the mandatory field "Name" wasn't specified in the input payload. The resulting error message would be:
131
-
132
-
```json
133
-
{
134
-
"message": "Model validation failed",
135
-
"status": 400,
136
-
"code": "ModelValidationFailed",
137
-
"moreInfo": "[\"The Name field is required.\"]"
138
-
}
139
-
```
140
-
141
-
## Add users or app registrations to Azure Active Directory
142
-
143
-
Azure FarmBeats APIs can be accessed by a user or an app registration in Azure Active Directory. To create an app registration in Azure Active Directory, follow these steps.
144
-
145
-
1. Go to the [Azure portal](https://portal.azure.com), and select **Azure Active Directory** > **App registrations** > **New registration**. Alternatively, you can use an existing account.
146
-
2. For a new account, do the following:
147
-
148
-
- Enter a name.
149
-
- Select **Accounts in this organizational directory only (Single tenant)**.
150
-
- Use the default values in the rest of the fields.
151
-
- Select **Register**.
152
-
153
-
3. On the new and existing app registration **Overview** pane, do the following:
154
-
155
-
- Capture the **Client ID** and **Tenant ID**.
156
-
- Go to **Certificates and Secrets** to generate a new client secret and capture the **Client-Secret**.
157
-
- Go back to **Overview**, and select the link next to **Manage Application in local directory**.
158
-
- Go to **Properties** to capture the **Object ID**.
159
-
160
-
4. Go to your [Datahub Swagger](https://<yourdatahub>.azurewebsites.net/swagger/index.html) and do the following:
161
-
- Go to the **RoleAssignment API**.
162
-
- Perform a POST to create a **RoleAssignment** object for the **Object ID** you just created.
163
-
164
-
> [!NOTE]
165
-
> For more information on how to add users and Active Directory registration, see [Azure Active Directory](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal).
166
-
167
-
After you finish the previous steps, your app registration (client) can call the Azure FarmBeats APIs by using an access token via bearer authentication.
168
-
169
-
Use the access token to send it in subsequent API requests in the header section as:
0 commit comments