Sensores

El servicio de sensores está diseñado para monitorear el valor en el tiempo de ciertas variables.

Estructura

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.

A cada variable se le puede ingestar values, y cada value consiste de un timestamp, un valor y metadata opcional.

Acceso

El acceso a variables se hace por grupo, lo que permite el manejo de todas la variables dentro de él.

Sensores es una herramienta atada a Extensiones. Los grupos/variables sólo pueden ser creados/editados por extensiones.

Las extensiones interactúan con sensores en nombre de un usuario, pudiendo acceder sólo a las variables creadas por esa extensión y para ese usuario. En cambio, el usuario puede ver sus variables creadas por todas las extensiones.

Variables model

Permisos

Cada acción sobre variables tiene una funcionalidad asociada. El usuario que ejecute la acción debe tenerla habilitada (según el plan). Además, cuando una extensión es desde donde se ejecute la acción, se verificará que esta tenga la funcionalidad activa en el claimset.

Requiere tener activo en el claimset las funcionalidades Variables y Variables Groups.

Funcionalidades

VARIABLE_GROUPS_CREATE: Crea un grupo de variables para la extensión y usuario actual.
VARIABLE_GROUPS_READ: Lee un grupo de variables de la extensión y usuario actual.
VARIABLE_GROUPS_UPDATE: Actualiza un grupo de variables de la extensión y usuario actual.
VARIABLE_GROUPS_DELETE: Elimina un grupo de variables de la extensión y usuario actual.
VARIABLES_CREATE: Crea una variable para la extensión y usuario actual dentro de un grupo específico.
VARIABLES_READ: Lee una variable de un grupo perteneciente a la extensión y usuario actual.
VARIABLES_UPDATE: Actualiza una variable de un grupo perteneciente a la extensión y usuario actual.
VARIABLES_DELETE: Elimina una variable de un grupo perteneciente a la extensión y usuario actual.

Objetos

Objeto `variable_group`:

group_uuid: string, uuid del grupo.
created_at: string, fecha de creación. Formato YYYY-MM-DDTHH:MM:SSZ
deleted_at: string, fecha de eliminación. Formato YYYY-MM-DDTHH:MM:SSZ. Puede ser nula (no eliminado)
group_name: string, nombre del grupo.
user_group_name: string, nombre del grupo seteado por el usuario en auravant.
device: string, número de serie del grupo.
position: string, posición en el mapa. Puede ser nula
user_position: string, posición en el mapa seteado por el usuario en auravant. Puede ser nula
timezone_offset: integer, con la cantidad de minutos de offset respecto a UTC del grupo
metadata: object, con metadata. Contiene únicamente las licencias de cultivos. {"licenses": {}}
variables: array, con objetos variables. Puede ser un array vacío.

Objeto `variable`:

variable_uuid: string, uuid de la variable
created_at: string, fecha de creación. Formato YYYY-MM-DDTHH:MM:SSZ
deleted_at: string, fecha de eliminación. Formato YYYY-MM-DDTHH:MM:SSZ. Puede ser nula (no eliminado)
variable_name: string, nombre de la variable.
user_variable_name: string, nombre de la variable seteado por el usuario en auravant.
device: string, número de serie de la variable.
metadata: object, con metadata.
last_value: float, último valor. Puede ser Nulo
last_value_time: string, fecha del último valor. formato YYYY-MM-DDTHH:MM:SSZ. Puede ser Nulo.
group_uuid: string, uuid del grupo.

Objeto `values`:

timestamps: array(string), array de fechas. formato YYYY-MM-DDTHH:MM:SSZ
values: array(float), array de valores.
metadata: array(object), array de objetos de metadata.

Los tres arrays tienen el mismo largo y los elementos en la misma posición se corresponden entre si. Por ejemplo, para el elemento timestamps[0], la variable tiene el valor values[0] y la metadata metadata[0].

API

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

Grupos

GET

Este endpoint permite obtener los grupos de variables creados y su información.

Requiere funcionalidad Variable groups - read (R)

Authorization: Bearer TOKEN
GET /providers/variablegroups

Si se quiere obtener un variable_group en específico se debe agregar el group_uuid en la query string.

Ejemplo de respuesta:

{
	"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": []
		}
	]
}

Donde data es un array de objetos: variable_groups

POST

Este endpoint permite crear un nuevo grupo de variables

Requiere funcionalidad 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> `requerido`,
    "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 será asignado con la fecha actual si no se envía

deleted_at, user_group_name & user_position serán asignados como null si no se envían

timezone_offset será asignado con 0 si no se envía. No puede ser null

metadata será asignado como un objeto vacío si no se envía

variables será asignado como array vacío si no se envía

Ejemplo de respuesta:

{
	"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"
}

Donde data es un objeto de variable_group con los datos cargados.

PATCH

Este endpoint permite actualizar o modificar un grupo de variables

Requiere funcionalidad Variable groups - update (U)

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

NOTAS

Nótese que se pueden modificar todos los campos del objeto variable_group a excepción de los datos que corresponden al usuario: user_group_name y user_position

Solo se deben enviar los campos que se vayan a modificar

Ejemplo de respuesta:

{
	"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"
}

Donde data es un objeto de variable_groups con los datos nuevos

DELETE

Este endpoint permite eliminar un grupo de variables

Requiere funcionalidad Variable groups - delete (D)

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

Donde group_uuid es un string que corresponde al uuid del grupo.

Ejemplo de respuesta:

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

Variables

POST

Este enpoint permite crear una nueva variable dentro de un grupo

Requiere funcionalidad 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"
}

Donde data es un objeto de variable con los datos cargados.

PATCH

Este endpoint permite actualizar o modificar una variable creada.

Requiere funcionalidad 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>
}

IMPORTANTE - Solo se pueden modificar los valores especificados. Al intentar modificar cualquier otro no se aplicarán los cambios.

Ejemplo de respuesta:

{
	"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"
}

Donde data es un objeto de variable con los datos nuevos

DELETE

Este endpoint permite borrar una variable creada.

Requiere funcionalidad Variables - delete (D)

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

Donde variable_uuid es un string que corresponde al uuid de la variable.

Ejemplo de respuesta:

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

Valores

POST

Requiere funcionalidad Variables - create (C)

Este endpoint permite insertar valores para determinada variable.

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

IMPORTANTE - La cantidad máxima de valores que se pueden ingresar es de 2.000.000

Ejemplo de respuesta:

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

Si no se envía ningun valor el endpoint devuelve un código http 204 con el mensaje: "no values were inserted".

Si el número de valores a ingresar es mayor al especificado, el endpoint responde con el mensaje: "Total number of values to insert must not exceed 2.000.000"

Errores generales

En caso de fallar alguna consulta, la respuesta tendrá un código http mayor a 400 y un cuerpo en formato json con un código que indicará lo sucedido.

Ejemplo:

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

Según el código, se le debe informar al usuario lo que sucedió. Existen códigos de error generales que pueden ocurrir en todos los endpoints. A su vez, cada endpoint tiene códigos especificos detallados en la especificación de cada uno.

Códigos generales

CODE	INFO	Descripción
GENERAL_ERROR	The requested action failed to execute	Error general, es generalmente un error no atajado
EXPIRED_AUTHENTICATION	Expired Authentication token	Token vencido, no debería ocurrir desde la extensión
INVALID_AUTH	Invalid Authentication token	Token inválido, no debería ocurrir desde la extensión
PARAMETER_ERROR	Parameters error	Los parámetros enviados no coinciden con los esperados
UNAUTHORIZED_EXTENSION	Unauthorized attempt to access an Extensions resource	Se está consultando un endpoint no habilitado para extensiones
UNAUTHORIZED_USER	Unauthorized attempt to access a protected endpoint	Usuario no autenticado, falta autenticación en la request
ACCESS_ERROR	The User does not have access to the requested resource	Se está intentando acceder a un grupo/variable sobre el cual no se tiene acceso
PERMISSION_ERROR	The User is not allowed to execute the specified action over the requested resource	El usuario no cuenta con la funcionalidad para ejecutar la acción solicitada

Códigos específicos

CODE	INFO	Descripción
VARIABLEGROUP_NOT_FOUND	Variable group could not be found	No se encontró el grupo solicitado
VARIABLEGROUP_CREATE_ERROR	Variable group could not be created	No se pudo crear el grupo
VARIABLEGROUP_UPDATE_ERROR	Variable group could not be updated	No se pudo actualizar el grupo
VARIABLEGROUP_DELETE_ERROR	Variable group could not be deleted	No se pudo eliminar el grupo
VARIABLE_NOT_FOUND	Variable could not be found	No se encontró la variable solicitada
VARIABLE_CREATE_ERROR	Variable could not be created	No se pudo crear la variable
VARIABLE_UPDATE_ERROR	Variable could not be updated	No se pudo actualizar la variable
VARIABLE_DELETE_ERROR	Variable could not be deleted	No se pudo eliminar la variable

Estructura​

Acceso​

Permisos​

Funcionalidades​

Objetos​

Objeto variable_group:​

Objeto variable:​

Objeto values:​

API​

Grupos​

GET​

POST​

PATCH​

DELETE​

Variables​

POST​

PATCH​

DELETE​

Valores​

POST​

Errores generales​

Códigos generales​

Códigos específicos​

Estructura

Acceso

Permisos

Funcionalidades

Objetos

Objeto `variable_group`:

Objeto `variable`:

Objeto `values`:

API

Grupos

GET

POST

PATCH

DELETE

Variables

POST

PATCH

DELETE

Valores

POST

Errores generales

Códigos generales

Códigos específicos