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 Screenshot 2024-10-04 at 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.

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:

  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 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