Scripts de Servicios Web
Los Scripts de Servicios Web proporcionan una solución flexible para crear y publicar Servicios Web personalizados utilizando Javascript.
Puedes usar REST para interactuar con el Servidor de GpsGate, pero anteriormente tenías que crear tu propio adaptador si necesitabas traducir el formato de datos para adaptarlo a tu sistema heredado. Esto ya no es necesario, ya que puedes configurar tus Servicios Web personalizados dentro del Servidor de GpsGate para comunicarte con sistemas externos que requieren formatos de datos específicos.
Configuración
1. Inicia sesión como Administración del sitio en la aplicación.
2. Accede a las propiedades de la aplicación
3. Habilita los privilegios: _EditScriptApp, _EditWebServiceScript y _WebServiceScriptLogin como se muestra a continuación.
4. Haz clic en Guardar
Creación de un Script de Servicio Web
1. Inicia sesión en tu aplicación
2. Haz clic en Menú Principal > Admin > Desarrollo > Constructor de Apps.
3. Crea una nueva app
4. Asigna un nuevo nombre a tu aplicación de script web y haz clic en Guardar.
5. Ve a la sección Scripts de Servicios Web. Haz clic en el botón + Script.
6. Completa los detalles para el servicio web.
7. Haz clic en el botón Editar. La ventana del editor de scripts aparece con la plantilla de script predeterminada.
Si tienes experiencia con otros tipos de scripts en la plataforma GpsGate, la interfaz del editor te resultará familiar.
La lista de objetos expuestos está en el lado derecho. Los campos de entrada editables se pueden usar para establecer datos de prueba al hacer clic en el botón Ejecutar Script.
Ejemplo
Normalmente, un script de servicio web consta de tres partes principales:
- Análisis de los parámetros de la solicitud desde la URL o el cuerpo de la solicitud
- Interacción con el servidor de GpsGate a través de funciones JavaScript expuestas
- Creación del cuerpo de la respuesta
Aprendamos cómo usar el marco de JavaScript para implementar estos pasos. Echa un vistazo a la sección de API del artículo para obtener más documentación de la API que no se cubre en el ejemplo. La lista actual de funciones expuestas es limitada. Se ampliará caso por caso.
En este ejemplo, creamos un Servicio Web para devolver la última posición de un activo. El sistema consumidor del Servicio Web solicita los datos en el formato que se muestra a continuación. Se autentica utilizando las credenciales especificadas en el nodo XML de inicio de sesión. El usuario necesita tener los privilegios _WebServiceScriptLogin, _ReadUsers y _ReadData para poder acceder al activo especificado.
< request >
< login >
< user >username</ user >
< pass >password</ pass ></ login >< assetid >123</ assetid >
</ request >
|
El sistema consumidor del servicio espera la respuesta en el siguiente formato:
< response >
< lat >1</ lat >
< long >2</ long >
</ response >
|
Ejemplo de script
var xmlReq = xml.parseFromString(request.body);
var usuario = xmlReq.selectSingleNode( '/request/login/user' ).innerText;
var pass = xmlReq.selectSingleNode( '/request/login/pass' ).innerText;
auth.login(usuario, pass); // el usuario necesita privilegio _WebServiceScriptLogin
var assetID = xmlReq.selectSingleNode( '/request/assetid' ).innerText;
var usuario = directory.getUserByID(assetID);
if (usuario != null ) {
var lat = usuario.trackPoint.position.latitude;
var lon = usuario.trackPoint.position.longitude;
response.body =
'<response>’ +
‘<lat>’ + lat + ‘</lat>’ +
‘<long>’ + lon + ‘</long>’ +
‘</reponse>’;
} else {
response.body = ' <response><error>No encontrado</error></response>';
} |
En el navegador de objetos, complete el cuerpo de la solicitud con datos de prueba y luego haga clic en el botón Probar Script. Verá la respuesta en la consola del editor de scripts.
Nota: necesita autenticar el sistema consumidor del servicio web para poder acceder a los datos. Es una buena práctica crear un usuario separado para el servicio con el conjunto de privilegios mínimos necesarios. El plugin AccessFilter hace posible controlar qué direcciones IP pueden acceder a su servicio.
Nota: se utiliza el formato XML en los ejemplos anteriores, pero también es posible comunicarse utilizando el formato JSON (consulte las funciones JSON.stringify(obj) y JSON.parse(str))
Nota: los métodos de la API pueden lanzar excepciones en caso de falta de privilegios, etc. Use try-catch para manejar esos errores.
Habilitar el registro en tiempo de ejecución
Puede habilitar la función de registro para Scripts de Servicio Web en tiempo de ejecución editando el archivo Nlog.config en la carpeta del servicio NMEA bajo la carpeta de instalación del Servidor GpsGate (si no está alojando su propio servidor, por favor contacte al soporte). Bajo <targets>, debe agregar una nueva entrada de destino como esta:
|
.
< target name = "TARGET_NAME" xsi:type = "File" fileName = "FILE_NAME" layout = "${longdate} | ${message}" />
. |
donde TARGET_NAME es un nombre único para el destino del archivo y FILE_NAME es el nombre del archivo de registro que desea crear con la ruta completa al archivo. Bajo <rules>, agregue una entrada como esta:
|
< logger name = "NAME_OF_WEB_SERVICE_SCRIPT" minlevel = "Info" writeTo = "TARGET_NAME" />
|
donde NAME_OF_WEB_SERVICE_SCRIPT es el nombre del script de clic que deseas registrar en el archivo, y TARGET_NAME es el nombre único del objetivo que agregaste anteriormente. Los datos registrados a través del método log en el script del servicio web especificado se escribirán en el archivo especificado.
API
request:
- body: string
Cuerpo de la solicitud. - query: string
Cadena de consulta de la solicitud. - queryParams : NameValueCollection
Representa una colección de parámetros de cadena de consulta.
xml:
- parseFromString(strXml) : XmlDocument
Devuelve un objeto de documento que representa el árbol DOM de la fuente XML. - createDocument() : XmlDocument
Devuelve un nuevo objeto de documento XML vacío.
JSON: (añadido en la versión 4.0.0.2174)
- stringify(object) : string
Convierte un valor a JSON - parse(str) : object
Analiza una cadena como JSON.
auth:
- login(strUsername, strPassword) : string
Autentica a un usuario con contraseña y devuelve el id de sesión. - login(strSessionId)
Autentica a un usuario con id de sesión.
customFields:
- getValues(strNamespace, iObjectID) : array of CustomFieldValue
Devuelve los Campos Personalizados para el objeto especificado. El valor de strNamespace puede ser ‘user’ o ‘poi’.
directory:
- getUserByID(iUserID) : GateUser
Devuelve un usuario por id de usuario. - getUserByIMEI(strIMEI) : GateUser
Devuelve un usuario por IMEI. - getUsers() : array of GateUser
(añadido en la versión 4.0.0.2174)
Devuelve todos los usuarios en la aplicación actual - getLatestRecords(iUserID) : array of MessageRecord
Devuelve el último valor de las variables.
tags (añadido en la versión 4.0.0.2174)
- getTags() : array of UserTag
Obtiene todas las etiquetas en la aplicación. - getTagByName(strName) : UserTag
Devuelve la etiqueta de usuario que tiene el nombre especificado. - updateUsers(iTagID, userIDsToAdd, userIDsToRemove) : UserTag
Agrega/Elimina usuarios a/de la etiqueta especificada.
geo (añadido en la versión 4.0.0.2190)
- reverseGeocode(lat, lng) : Location
Resuelve una geo-localización en una dirección.
log(valueOrObject) : void
Esta función registra el valor en el archivo de registro o en la consola del editor de scripts.
Tipos que no se exponen explícitamente como miembros raíz:
CustomFieldValue
- name : string
El nombre del campo. - value : string
El valor del campo.
GateUser
- id : int
Id de usuario. - name : string
Nombre de usuario. - username: string
Nombre de usuario. - trackPoint: TrackPoint
Último TrackPoint válido para el usuario.
UserTag
- id : entero
El id de la etiqueta de usuario. - name : cadena
El nombre de la etiqueta de usuario. - description : cadena
La descripción de la etiqueta de usuario. - userIDs : arreglo de enteros
IDs de Usuario asociados a la etiqueta.
MessageRecord
- name: cadena
Nombre del campo. - value: objeto
Valor del campo - type: cadena
Tipo del campo - unit: cadena
Unidad del campo. - utc: JsDate
Especifica cuándo se registró el valor.
NameValueCollection:
- get(strName) : cadena
Obtiene el valor asociado con la clave especificada.
XmlNode:
- nodeName : cadena
El nombre de este nodo. - nodeValue : cadena
El valor de este nodo. - innerText : cadena
Obtiene los valores concatenados del nodo y todos sus nodos hijos. - nodeType: entero
Un código que representa el tipo del objeto subyacente. - nodeTypeName : cadena
Un nombre de tipo que representa el tipo del objeto subyacente. - hasChildNodes : bool
Devuelve si este nodo tiene hijos. - childNodes : XmlNodeList
Una NodeList que contiene todos los hijos de este nodo. Si no hay hijos, esta es una NodeList que no contiene nodos.
(for(var child in node.childNodes){} también funciona) - appendChild(XmlNode) : XmlNode
Agrega el nodo especificado al final de la lista de nodos hijos de este nodo. - selectNodes(strXPath) : XmlNodeList
Selecciona una lista de nodos que coinciden con la expresión XPath.
(for(var child in node.childNodes){} también funciona) - selectSingleNode(strXPath) : XmlNode
Selecciona el primer nodo que coincide con la expresión XPath.
XmlNodeList:
- length : entero
El número de nodos en la lista. - [index] : XmlNode
Devuelve el elemento de la posición especificada.
XmlDocument : XmlNode
- createElement(strName) : XmlElement
Crea un elemento con el nombre especificado. - createTextNode(strText) : XmlText
Crea un nodo de texto con el contenido especificado. - outerXml: cadena
Obtiene el marcado que representa este nodo y todos sus nodos hijos.
XmlElement: XmlNode
XmlText: XmlNode