Skip to main content

Sensors

The sensors service is designed to monitor the value over time of certain variables.

Structure

La unidad básica para el uso de sensores son las variables. Estas están agrupadas en grupos llamados variable_groups. Finalmente, estos grupos corresponden a un par usuario/extension, es decir, para acceder a un grupo de variables se debe identificar al usuario y a la extenión a los que corresponde cada grupo.

The basic unit for the use of sensors are variables. These are grouped into variable_groups. Finally, these groups correspond to a user/extension pair, that is, to access a group of variables, the user and the extension, to which each group corresponds, must be identified.

Each variable can ingest values, and each value consists of a timestamp, a value, and optional metadata.

Access

Access to variables is done by group, which allows the management of all the variables within it.

Sensors is a tool tied to Extensions. groups/variables can only be created or edited by Extensions.

Extensions interact with sensors on behalf of a user, being able to access only variables created by that extension and for that user. Instead, the user can see his variables created by all extensions.

Variables model Variables model

Permissions

Each action on variables has an associated functionality. The user executing the action must have it enabled (according to the premium plan). Also, when an extension is where the action is executed from, it will be verified that it has the active functionality in the claimset.

Requires having the Variables and Variables Groups functionalities active in the claimset.

Functionalities

  • VARIABLE_GROUPS_CREATE: Create a group of variables for the extension and current user.

  • VARIABLE_GROUPS_READ: Read a group of variables from the current extension and user.

  • VARIABLE_GROUPS_UPDATE: Updates a group of variables of the current extension and user.

  • VARIABLE_GROUPS_DELETE: Deletes a group of variables from the current extension and user.

  • VARIABLES_CREATE: Create a variable for the current extension and user within a specific group.

  • VARIABLES_READ: Reads a variable from a group belonging to the extension and current user.

  • VARIABLES_UPDATE: Updates a variable of a group belonging to the extension and current user.

  • VARIABLES_DELETE: Deletes a variable from a group belonging to the extension and current user.

Objects

variable_group object:

  • group_uuid: string, group uuid.
  • created_at: string, creation date. Format YYYY-MM-DDTHH:MM:SSZ
  • deleted_at: string, date deleted. Format YYYY-MM-DDTHH:MM:SSZ. May be null (not deleted)
  • group_name: string, group name.
  • user_group_name: string, name of the group set by the user in auravant.
  • device: string, group serial number.
  • position: string, position on the map. can be null
  • user_position: string, position on the map set by the user in auravant. can be null
  • timezone_offset: integer, with the number of minutes offset from UTC of the group
  • metadata: object, with metadata. Contains only crop licenses. {"licenses": {}}
  • variables: array, with variable objects. It can be an empty array.

variable object:

  • variable_uuid: string, variable uuid
  • created_at: string, creation date. Format YYYY-MM-DDTHH:MM:SSZ
  • deleted_at: string, date deleted. Format YYYY-MM-DDTHH:MM:SSZ. May be null (not deleted)
  • variable_name: string, variable name.
  • user_variable_name: string, name of the variable set by the user in auravant.
  • device: string, variable serial number.
  • metadata: object, with metadata.
  • last_value: float, last value. can be null
  • last_value_time: string, date of last value. format YYYY-MM-DDTHH:MM:SSZ. It can be Null.
  • group_uuid: string, group uuid.

values object:

  • timestamps: array(string), array of dates. format YYYY-MM-DDTHH:MM:SSZ
  • values: array(float), array of values.
  • metadata: array(object), array of metadata objects.

All three arrays have the same length and elements in the same position correspond to each other. For example, for the element timestamps[0], the variable has the value values[0] and the metadata metadata[0].

API

BASE URL: https://api.auravant.com/sensors/v2

Groups

GET

This endpoint allows you to obtain the groups of variables created and their information.

Requires functionality Variable groups - read (R)

Authorization: Bearer TOKEN
GET /providers/variablegroups

If you want to obtain a specific variable_group, you must add the group_uuid in the query string.

Response example:

{
"res": "ok",
"data": [
{
"group_uuid": "e4f4f23b-037a-4a6f-b118-f453eae33c95",
"created_at": "2022-06-13T21:22:33Z",
"deleted_at": null,
"group_name": "test-variable-group-1",
"user_group_name": null,
"device": "",
"position": "",
"user_position": null,
"timezone_offset": 0,
"metadata": {},
"variables": []
},
{
"group_uuid": "809cbdc8-30e2-406b-9740-8ce32b2bb6f0",
"created_at": "2022-06-14T11:20:04Z",
"deleted_at": null,
"group_name": "test-variable-group-2",
"user_group_name": null,
"device": "",
"position": "",
"user_position": null,
"timezone_offset": 0,
"metadata": {},
"variables": []
},
{
"group_uuid": "5795a90e-b90e-40df-9b21-b68e1daf9609",
"created_at": "2022-06-14T11:20:48Z",
"deleted_at": null,
"group_name": "test-variable-group-3",
"user_group_name": null,
"device": "",
"position": "",
"user_position": null,
"timezone_offset": 0,
"metadata": {},
"variables": []
}
]
}

Where data is an array of data objects: variable_groups

POST

This endpoint allows you to create a new group of variables

Requires functionality Variable groups - create (C)

Authorization: Bearer TOKEN
Content-Type: application/json
POST /providers/variablegroups
Body:
{
"group_uuid": <GROUP_UUID>,
"created_at": <CREATED_AT>,
"deleted_at": <DELETED_AT>,
"group_name": <GROUP_NAME> `required`,
"user_group_name": <USER_GROUP_NAME>,
"device": <DEVICE>,
"position": <POSITION>,
"user_position": <USER_POSITION>,
"timezone_offset": <TIMEZONE_OFFSET>,
"metadata": <METADATA>,
"variables": <VARIABLES>
}

NOTAS

  • created_at will be assigned automatically with the current date if was not sent
  • deleted_at, user_group_name & user_position will be assigned as null if was not sent
  • timezone_offset will be assigned as 0 if was not sent. Cannot be null
  • metadata will be assigned as an empty object if was not sent
  • variables will be assigned as an empty array if was mot sent

Response example:

{
"res": "ok",
"data": {
"group_uuid": "5795a90e-b90e-40df-9b21-b68e1daf9609",
"created_at": "2022-06-14T11:20:48Z",
"deleted_at": null,
"group_name": "test-variable-group-3",
"user_group_name": null,
"device": "",
"position": "",
"user_position": null,
"timezone_offset": 0,
"metadata": {},
"variables": []
},
"info": "variable group created successfully"
}

Where data is an object of the variable_group type with the loaded data.

PATCH

This endpoint allows updating or modifying a group of variables

Requires functionality Variable groups - update (U)

Authorization: Bearer TOKEN
Content-Type: application/json
PATCH /providers/variablegroups
Body:
{
"group_uuid": <GROUP_UUID> `required`,
"created_at": <CREATED_AT>,
"deleted_at": <DELETED_AT>,
"group_name": <GROUP_NAME>,
"device": <DEVICE>,
"position": <POSITION>,
"timezone_offset": <TIMEZONE_OFFSET>,
"metadata": <METADATA>,
"variables": <VARIABLES>
}

NOTES

  • Note that all the fields of the object variable_group can be modified except for the data that corresponds to the user: user_group_name and user_position
  • Only properties to be modified should be sent

Response example:

{
"res": "ok",
"data": {
"group_uuid": "e4f4f23b-037a-4a6f-b118-f453eae33c95",
"created_at": "2022-06-13T21:22:33Z",
"deleted_at": null,
"group_name": "test-variable-group-1",
"user_group_name": null,
"device": "",
"position": "",
"user_position": null,
"timezone_offset": 4,
"metadata": {},
"variables": []
},
"info": "variable group updated successfully"
}

Where data is an object of the variable_groups type with the new data.

DELETE

This endpoint allows you to delete a group of variables

Requires functionality Variable groups - delete (D)

Authorization: Bearer TOKEN
Content-Type: application/json
DELETE /providers/variablegroups
Body:
{
"group_uuid": <GROUP_UUID>, `required`
}

Where group_uuid is a string corresponding to the uuid of the group.

Response example:

{
"res": "ok",
"info": "variable group deleted successfully"
}

Variables

POST

This enpoint allows to create a new variable within a group

Requires functionality Variables - create (C)

Authorization: Bearer TOKEN
Content-Type: application/json
POST /providers/variables
Body:
{
"group_uuid": <GROUP_UUID> `requerido`,
"variable": {
"variable_name": <VARIABLE_NAME> `requerido`,
"device": <DEVICE>,
"metadata: <METADATA>
}
}

Ejemplo de respuesta:

{
"res": "ok",
"data": {
"variable_uuid": "3120deb3-3079-4d78-92a0-b5a82000e921",
"variable_name": "test-variable-1",
"user_variable_name": null,
"group_id": 582,
"created_at": "2022-06-14T13:14:50Z",
"deleted_at": null,
"device": null,
"metadata": null,
"last_value": null,
"last_value_time": null
},
"info": "variable created successfully"
}

Where data is an object of the variable type with the data loaded

PATCH

This endpoint allows you to update or modify a created variable.

Requires functionality Variable groups - update (U)

Authorization: Bearer TOKEN
Content-Type: application/json
PATCH /providers/variables
Body:
{
"variable_uuid": <VARIABLE_UUID> `requerido`,
"variable_name": <VARIABLE_NAME>,
"device": <DEVICE>,
"metadata": <METADATA>
}

NOTE - Only specified values can be modified. When trying to modify any other key changes are not applied

Response example:

{
"res": "ok",
"data": {
"variable_uuid": "b3e18dbf-f60c-4403-808f-59ead5796304",
"variable_name": "test-variable-1",
"user_variable_name": null,
"group_id": 582,
"created_at": "2022-06-14T13:03:18Z",
"deleted_at": null,
"device": "medidor-1",
"metadata": {
"key-1": "metadata-1"
},
"last_value": null,
"last_value_time": null
},
"info": "variable updated successfully"
}

Where data is an object of variable with the new data

DELETE

This endpoint allows you to delete a created variable.

Requires functionality Variables - delete (D)

Authorization: Bearer TOKEN
Content-Type: application/json
DELETE /providers/variables
Body:
{
"variable_uuid": <VARIABLE_UUID>, `required`
}

Where variable_uuid is a string corresponding to the uuid of the variable.

Response example:

{
"res": "ok",
"info": "variable deleted successfully"
}

Values

POST

Requires functionality Variables - create (C)

This endpoint allows you to insert values ​​for a certain variable.

Authorization: Bearer TOKEN
Content-Type: application/json
POST /providers/values/variables
Body:
{
"data": [
{
"variable_uuid": <VARIABLE_UUID> `required`,
"values": <VALUES> `required`,
"metadata": <DATA>,
"timestamps": <DATES> `required`
},
{...},
...
]
}

IMPORTANT - The maximum number of values ​​that can be entered is 2,000,000

Response example:

{
"res": "ok",
"info": "values inserted"
}

If no value is sent, the endpoint returns an http code 204 with the message: "no values ​​were inserted".

If the number of values ​​to insert is greater than the specified, the endpoint responds with the message: "Total number of values ​​to insert must not exceed 2,000,000"

General errors

If any query fails, the response will have an http code greater than 400 and a body in json format with a code that will indicate what happened.

Example:

{
"res": "error",
"code": <CODE>,
"info": <INFO>
}

According to the code, the user should be told what happened. There are general error codes that can occur on all endpoints. In turn, each endpoint has specific codes detailed in the specification of each one.

General codes

CODEINFO
GENERAL_ERRORThe requested action failed to execute
EXPIRED_AUTHENTICATIONExpired Authentication token
INVALID_AUTHInvalid Authentication token
PARAMETER_ERRORParameters error
UNAUTHORIZED_EXTENSIONUnauthorized attempt to access an Extensions resource
UNAUTHORIZED_USERUnauthorized attempt to access a protected endpoint
ACCESS_ERRORThe User does not have access to the requested resource
PERMISSION_ERRORThe User is not allowed to execute the specified action over the requested resource

Specific codes

CODEINFO
VARIABLEGROUP_NOT_FOUNDVariable group could not be found
VARIABLEGROUP_CREATE_ERRORVariable group could not be created
VARIABLEGROUP_UPDATE_ERRORVariable group could not be updated
VARIABLEGROUP_DELETE_ERRORVariable group could not be deleted
VARIABLE_NOT_FOUNDVariable could not be found
VARIABLE_CREATE_ERRORVariable could not be created
VARIABLE_UPDATE_ERRORVariable could not be updated
VARIABLE_DELETE_ERRORVariable could not be deleted