Avatar
Andreea
  • Actualización

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.

Privilegios de ScriptApp con marcas de verificaciónPrivilegio WebServiceScriptLogin habilitado

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 Captura de pantalla 2024-10-04 a las 14.27.59.png > Admin > Desarrollo > Constructor de Apps.

3. Crea una nueva app mceclip2.png

4. Asigna un nuevo nombre a tu aplicación de script web y haz clic en Guardar.

Interfaz de configuración de la aplicación de script de servicio web

5. Ve a la sección Scripts de Servicios Web. Haz clic en el botón + Script.

Sección de scripts de servicios web con botón de agregar.

6. Rellena los detalles para el servicio web.

Interfaz de configuración de script de 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.

Editor de scripts con código y árbol de objetos

Ejemplo

Normalmente, un script de servicio web consta de tres partes principales:

  1. Análisis de los parámetros de la solicitud desde la URL o el cuerpo de la solicitud
  2. Interacción con el servidor de GpsGate a través de funciones JavaScript expuestas
  3. Creación del cuerpo de la respuesta

Aprendamos cómo usar el marco de trabajo 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 de inicio de sesión XML. 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 user = xmlReq.selectSingleNode('/request/login/user').innerText;
var pass = xmlReq.selectSingleNode('/request/login/pass').innerText;
auth.login(user, pass); // el usuario necesita el privilegio _WebServiceScriptLogin
 
var assetID = xmlReq.selectSingleNode('/request/assetid').innerText;
var user = directory.getUserByID(assetID);
 
if(user != null) {
    var lat = user.trackPoint.position.latitude;
    var lon = user.trackPoint.position.longitude;
  
  
    response.body =
      '<response>’ +
        ‘<lat>’ + lat + ‘</lat>’ +
        ‘<long>’ + lon + ‘</long>’ +
      ‘</reponse>’;
} else {
    response.body = '<response><error>Not found</error></response>';
}

En el navegador de objetos, llena el cuerpo de la solicitud con datos de prueba y luego haz clic en el botón Probar Script. Verás la respuesta en la consola del editor de scripts.

Nota: necesitas 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 mínimo de privilegios necesarios. El plugin AccessFilter permite controlar qué direcciones IP pueden acceder a tu servicio. 
Nota: se utiliza el formato XML en los ejemplos anteriores, pero también es posible comunicarse usando el formato JSON (consulta 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. Usa try-catch para manejar esos errores. 

Habilitar el registro en tiempo de ejecución

Puedes 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ás alojando tu propio servidor, por favor contacta con soporte). Bajo <targets>, deberías añadir 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 deseas crear con la ruta completa al archivo. Bajo <rules>, añade 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 destino que añadiste arriba. Los datos registrados a través del método de registro 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 valor más reciente de las variables.

Groups (Tags) (añadido en la versión 4.0.0.2174)

  • getTags() : array of UserTag
    Obtiene todos los Grupos (Tags) en la aplicación.
  • getTagByName(strName) : UserTag
    Devuelve el usertag que tiene el nombre especificado.
  • updateUsers(iTagID, userIDsToAdd, userIDsToRemove) : UserTag
    Añade/Elimina usuarios al/del Grupo (Tag) especificado.

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 : integer
    El id del Grupo de usuarios (Tag).
  • name : string
    El nombre del Grupo de usuarios (Tag).
  • description : string
    La descripción del Grupo de usuarios (Tag).
  • userIDs : array of integers
    IDs de Usuario asociados al Grupo (Tag).

MessageRecord

  • name: string
    Nombre del campo.
  • value: object
    Valor del campo
  • type: string
    Tipo del campo
  • unit: string
    Unidad del campo.
  • utc: JsDate
    Especifica cuándo se registró el valor.

NameValueCollection:

  • get(strName) : string
    Obtiene el valor asociado con la clave especificada.

XmlNode:

  • nodeName : string
    El nombre de este nodo.
  • nodeValue : string
    El valor de este nodo.
  • innerText : string
    Obtiene los valores concatenados del nodo y todos sus nodos hijos.
  • nodeType: int
    Un código que representa el tipo del objeto subyacente.
  • nodeTypeName : string
    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
    Añade 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 : int
    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: string
    Obtiene el marcado que representa este nodo y todos sus nodos hijos.

XmlElement: XmlNode

XmlText: XmlNode

Artículos relacionados