El SDK (Software Development Kit) es un conjunto de herramientas para desarrollar aplicaciones propias. El SDK de Wialon incluye varios API. El más básico de ellos es el Remote API, al cual están dirigidos estos artículos. El Remote API permite el acceso a los datos a través de solicitudes HTTP y es relevante para 1C, PHP, C++/C# y otros lenguajes de programación. El JS API y otros están construidos sobre la base del Remote API.

En este artículo se considerarán los conocimientos básicos necesarios para los principiantes en el uso del Remote API.

Visualización de solicitudes en el navegador

Al comenzar a estudiar el SDK, a menudo surge la necesidad de entender qué solicitud API se envía al servidor al realizar una u otra acción en la interfaz de Wialon. Esto se puede rastrear fácilmente utilizando las herramientas integradas del navegador para monitorear solicitudes de red.

En el navegador Chrome, se utiliza la pestaña Red de las Herramientas para desarrolladores, que se abren al presionar la tecla F12. En otros navegadores, esta herramienta puede abrirse de manera diferente, lo cual se puede leer en la documentación del navegador.

Al visualizar las solicitudes de red, se puede ver la solicitud enviada, sus parámetros y la respuesta del servidor API en formato JSON.

Formato de la solicitud

Las solicitudes HTTP se envían al servidor en el siguiente formato:

https://host/wialon/ajax.html?svc=REQUEST_NAME&params={PARAMETERS}&sid=SESSION_IDENTIFIER

Obtención de token y autorización

Para la autorización en Wialon se utiliza un token, es decir, una clave utilizada para la identificación cifrada del usuario.

Para crear un token, se puede utilizar el formulario oAuth. Después de un inicio de sesión exitoso, el token se mostrará en la barra de direcciones del navegador como el valor del parámetro formulario oAuth. Es importante tener en cuenta los parámetros adicionales que regulan propiedades como la duración (parámetro duration), el nombre de usuario (parámetro user), los derechos de acceso (parámetro access_type) y otros.

Ejemplo de formulario extendido para obtener un token:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

Ejemplo de respuesta:

https://hosting.wialon.com/login.html?lang=en&user=USER_NAME&wialon_sdk_url=https%3A%2F%2Fhst%2Dapi%2Ewialon%2Ecom&access_token=TOKEN_VALUE&svc_error=0

Después de obtener el token, se debe utilizar para la autorización. Ejemplo de inicio de sesión con token:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login&params={"token":"TOKEN_VALUE"}

En la respuesta al inicio de sesión con token, se incluye el parámetro eid, cuyo valor es el identificador único de sesión. Luego, se utilizará en casi todas las solicitudes API.

Configuración de la zona horaria

Por defecto, al trabajar con Remote API, los datos se muestran según la zona horaria GMT+0. Para cambiarla a la necesaria, se utiliza la solicitud render/set_locale. Es suficiente ejecutar esta solicitud en el marco de una sesión activa.

Al enviar la solicitud render/set_locale, es necesario utilizar el parámetro tzOffset. El método estándar para calcular su valor se describe en la documentación.

También se puede obtener el valor necesario del parámetro tzOffset mediante la visualización de solicitudes de red al cambiar la zona horaria del usuario en la interfaz web.

ID del sistema

En el API, el trabajo con casi todos los elementos se realiza a través de identificadores internos, llamados ID del sistema, que se presentan como valores numéricos únicos.

En las interfaces web, los ID del sistema no se muestran por defecto, pero se pueden ver de tres maneras:

1. En la respuesta a la solicitud de búsqueda de elementos por criterios (core/search_items). Se detallará en la siguiente sección de este artículo.
2. En los parámetros de las solicitudes al visualizar las solicitudes de red en el navegador.

3. En la columna avl_id en el sistema de gestión CMS Manager.

   Para que se muestre la columna avl_id, es necesario iniciar sesión en el CMS, añadiendo al final del enlace ?features=avl_id. Un ejemplo de dicho enlace se muestra en la imagen a continuación.
   
   

Búsqueda de elementos por criterios

Esta solicitud permite encontrar elementos según los criterios especificados en los parámetros.

La búsqueda se realiza por los siguientes tipos de elementos, que se indican en el campo itemsType:

• avl_hw — tipo de dispositivo;
  
• avl_resource — recurso;
  
• avl_retranslator — repetidor;
  
• avl_unit — unidad;
  
• avl_unit_group — grupo de unidades;
  
• user — usuario;
  
• avl_route — ruta.

Uno de los posibles criterios de búsqueda pueden ser los subelementos. En tal caso, para el parámetro propType se establece el valor propitemname, y el parámetro propName tomará los siguientes valores:

• Unidades:
  • unit_sensors — sensores;
  • unit_commands — comandos;
  • service_intervals — intervalos de servicio;
    
    
• Recursos:
  • drivers — conductores;
  • driver_groups — grupos de conductores;
  • jobs — tareas;
  • notifications — notificaciones;
  • trailers — remolques;
  • trailer_groups — grupos de remolques;
  • zones_library — geocercas;
  • reporttemplates — plantillas de informes;
  • orders — pedidos;
    
    
• Rutas:
  • rounds — rutinas;
  • route_schedules — horarios;
    
    
• Repetidores:
  • retranslator_units — unidades retransmitidas;
    
    
• Unidades, usuarios o recursos:
  • custom_fields — campos personalizados;
  • admin_fields — campos administrativos.

La información en la respuesta depende de los flags especificados en la solicitud de búsqueda en el parámetro flags. Los flags se establecen en formato DEC.

Veamos algunos ejemplos de uso de la solicitud de búsqueda de elementos por criterio (otros ejemplos se pueden encontrar en la documentación).

Búsqueda de elementos con un nombre específico

Es necesario obtener una lista de todas las unidades disponibles para el usuario, cuyo nombre contenga la palabra Tractor, así como información sobre los sensores creados en las unidades.

En tal caso, se puede utilizar la siguiente solicitud:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Tractor*","sortType":"sys_name"},"force":1,"flags":4097,"from":0,"to":0}&sid=SESSION_IDENTIFIER

{
	"searchSpec":{
		"itemsType":"avl_unit",
		"propName":"sys_name",
		"propValueMask":"*Tractor*",
		"sortType":"sys_name",
		"propType":"",
		"or_logic":"0"
	},
	"dataFlags":4097,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"Tractor 1",
			"cls":2,
			"id":22353120,
			"mu":0,
			"sens":{
				"1":{
					"id":1,
					"n":"Ignition",
					"t":"engine operation",
					"d":"",
					"m":"On\/Off",
					"p":"in1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"ci\":{},\"cm\":1,\"mu\":0,\"pos\":2,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				},
				"2":{
					"id":2,
					"n":"Fuel level",
					"t":"fuel level",
					"d":"",
					"m":"l",
					"p":"adc1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"calc_fuel\":0,\"ci\":{},\"cm\":1,\"fuel_params\":{\"fillingsJoinInterval\":300,\"filterQuality\":0,\"flags\":0,\"ignoreStayTimeout\":10,\"minFillingVolume\":20,\"minTheftTimeout\":0,\"minTheftVolume\":10,\"theftsJoinInterval\":300},\"mu\":0,\"pos\":1,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				}
			},
			"sens_max":-1,
			"uacl":-1
		}
	]
}

Búsqueda de usuarios creados después de una fecha específica

Es necesario obtener una lista de usuarios que fueron creados después del 23 de febrero de 2021 a las 05:41:46 (GMT+0). La respuesta debe contener los ID del sistema de estos usuarios y sus direcciones de correo electrónico.

En este caso, se puede utilizar la siguiente solicitud:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"user","propName":"rel_creation_time","propValueMask":">=1614058906","sortType":"sys_name"},"force":1,"flags":3,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Búsqueda de unidades de un tipo específico

Es necesario obtener una lista de unidades con el tipo de equipo Wialon Retranslator, que hayan enviado mensajes después del 12 de febrero de 2023 a las 12:00:00 (GMT+0). La respuesta debe mostrar los sensores de las unidades, el tiempo del último mensaje y las ubicaciones.

En este caso, se puede utilizar la siguiente solicitud:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"rel_hw_type_name,rel_last_msg_date","propValueMask":"Wialon%20Retranslator,>1676203200","sortType":"rel_creation_time"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Búsqueda de unidades por nombre de sensor

Es necesario obtener una lista de unidades en las que se haya creado un sensor con el nombre Engine.

En este caso, se puede utilizar la siguiente solicitud:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propType":"propitemname","propName":"unit_sensors","propValueMask":"Engine","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Búsqueda de grupos de unidades por varios criterios

Es necesario obtener una lista de grupos de unidades que fueron creados por el usuario User y en los que se hayan añadido más de 5 unidades.

En este caso, se puede utilizar la siguiente solicitud:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"rel_user_creator_name,rel_group_unit_count","propValueMask":"User,>5","sortType":"sys_name"},"force":1,"flags":133,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Lista de errores comunes

El error se muestra cuando no se puede ejecutar la solicitud. La lista completa de errores devueltos se puede encontrar en la documentación.

Los errores más comunes son:

• {error: 1} — sesión no válida. Este error se muestra cuando ha expirado el tiempo de vida del identificador único de sesión. Para corregir el error, basta con iniciar sesión con el token nuevamente y usar el nuevo identificador de sesión (sid) para ejecutar las solicitudes.

  Si no se ejecuta ninguna solicitud dentro de los 5 minutos en el marco de la sesión, esta se vuelve inactiva. Para mantener la sesión, puede enviar la solicitud avl_evts cada 5 minutos.

• {error: 4} — entrada no válida. Este error se muestra si hay un error en el texto de la solicitud: no se especifican todos los parámetros requeridos, los parámetros de texto no están entre comillas, falta un paréntesis de apertura o cierre, etc. Para corregir el error, es necesario corregir el texto de la solicitud según su descripción en la documentación.
  
  
• {error: 7} — acceso denegado. Este error se muestra si el usuario no tiene suficientes derechos para ejecutar la solicitud. Para corregir el error, es necesario verificar si el token utilizado para obtener el identificador único de sesión tiene suficientes flags de acceso, así como si el usuario para el cual se generó el token tiene suficientes derechos sobre los elementos utilizados.

Ekaterina Grib,Customer Service Engineer 2023-08-02