Retrieve orders¶
Description¶
This action allows you to retrieve the last orders associated with a sensor or provider. In addition,we can also specify search criteria to retrieve the orders: filter by a given time period and/or indicate the maximum number of orders that you want to retrieve.
http://<your_api_server.com>/order/<provider_id>/<sensor_id>?<parameter>=<value>
Format | json |
Method | GET |
Permission | Read |
Retorns | List of orders destined to sensor or provider listed |
Parameters¶
Key | Description | Optional |
---|---|---|
from | Indicates the beginning of the time period for which you want to retrieve orders. | Yes |
to | Indicates the ending of the time period for which you want to retrieve orders. | Yes |
limit | Specifies the maximum number of orders to retrieve. | Yes |
Please, note the following:
- The maximum number of records returned will be fixed by the platform settings. If the parameter passed is higher, the number of records returned will be the configured in the platform.
- If the limit parameter is not set, only one record will be returned.
- All dates must have the following format: dd/MM/yyyyTHH:mm:ss
Response data¶
As mentioned, in addition to HTTP status code, the requested data is returned in the body contents as a list of orders.
The response structure depends on what we are retrieving, orders from a sensor or a provider.
Last orders for a sensor¶
Key | Description | Optional |
---|---|---|
orders | List with the last sensor’s order | No |
Each order will have the following structure:
Key | Description | Optional |
---|---|---|
order | Order message recorded at the time the order was published | No |
timestamp | The time when the order was made (dd/MM/yyyyTHH:mm:ss format) | No |
sender | Entity identifier that issued the order. | No |
time | The time when the observation was made in milliseconds | No |
Last orders for provider¶
Key | Description | Optional |
---|---|---|
sensors | List with sensors (sensor) | No |
Each (sensor) will have the following structure:
Key | Description | Optional |
---|---|---|
sensor | Sensor identifier | No |
orders | List with the last orders for the sensor | No |
Finally, each command (order) will have the structure that we have defined previously.
Key | Description | Optional |
---|---|---|
order | Order message recorded at the time the order was published | No |
timestamp | The time when the order was made (dd/MM/yyyyTHH:mm:ss format) | No |
sender | Entity identifier that issued the order. | No |
Examples¶
Retrieve the last order for a sensor¶
To retrieve the last order for the sensor with RE0012 identifier belonging to the provider named rec, we do the following request:
http://<your_api_server.com>/order/rec/RE0012
As response we will get:
{"orders":[{
"order":"Shutdown",
"timestamp":"21/03/2013T14:25:39",
"sender":"app_demo_provider"}]
}
Retrieve the last N orders for a sensor¶
If we want to retreive more than one order, we can specify the number of records to retrieve with the following request:
http://<your_api_server.com>/order/rec/RE0012?limit=3
As response we will get:
{"orders":
[{
"order":"Shutdown",
"timestamp":"21/03/2013T14:25:39",
"sender":"app_demo_provider",
"time":1510570798597
},{
"order":"Start",
"timestamp":"20/03/2013T23:59:59",
"sender":"app_demo_provider",
"time":1510570798597
},{
"order":"Shutdown",
"timestamp":"20/03/2013T14:25:39",
"sender":"app_demo_provider",
"time":1510570798597
}
]}
Retrieve the last N orders for a sensor between dates¶
If we want to retrieve orders for a sensor between two dates, we should do the following request:
http://<your_api_server.com>/order/rec/RE0012?limit=3&from=19/03/2013T00:00:00&to=20/03/2013T23:59:59
As response we will get:
{"orders":
[{
"order":"Start",
"timestamp":"20/03/2013T23:59:59",
"sender":"app_demo_provider",
"time":1510570798597
},{
"order":"Shutdown",
"timestamp":"20/03/2013T14:25:39",
"sender":"app_demo_provider",
"time":1510570798597
}
]}
Retrieve the last orders for a provider¶
All the previous examples are focused on recovering the last command of a sensor, but the service also allows you to search the latest orders destined for all the sensors of provider.
In this case, we only specify the provider, and the request will be:
http://<your_api_server.com>/order/rec2
As response we get a list of sensor elements, and each one will contain its last orders.
{"sensors":
[{
"sensor":"RE0012",
"orders":
[{
"order":"Shutdown",
"timestamp":"21/03/2013T14:25:39",
"sender":"app_demo_provider",
"time":1510570798597
}]
},{
"sensor":"RE0013",
"orders":
[{
"order":"Shutdown",
"timestamp":"21/03/2013T14:25:39",
"sender":"app_demo_provider",
"time":1510570798597
}]
},{
"sensor":"RE0014",
"orders":
[{
"order":"Shutdown",
"timestamp":"21/03/2013T14:25:39",
"sender":"app_demo_provider",
"time":1510570798597
}]
}]
}