Scripts REST

NOTA:

El siguiente tema puede incluir referencias a aspectos relacionados con la programación personalizada de la línea de productos IndySoft. Es posible que algunos aspectos de las funciones mencionadas no estén disponibles para los clientes finales. A modo de referencia, las funciones afectadas incluirán la palabra «script» o «script personalizado».Consulte el tema «Descripción general de las secuencias de comandos personalizadas» para obtener más información sobre las secuencias de comandos personalizadas y sobre cómo se implementan y son compatibles con el producto.

Además, ten en cuenta que el uso de scripts REST para acceder a la base de datos de IndySoft a través de la web requerirá el registro del producto «IndySoft REST Scripting» en el módulo de registro de IndySoft. Póngase en contacto con el departamento de ventas de IndySoft para obtener más información. Si «IndySoft REST Scripting» se ha registrado como producto (mediante la utilidad de registro de IndySoft), se puede utilizar la pestaña «REST Scripts» para modificar los scripts y configurar el servicio REST de IndySoft correspondiente. Los scripts REST permiten el acceso web mediante scripts a la base de datos de IndySoft. La funcionalidad depende totalmente de los scripts creados y mantenidos en esta pestaña. REST es simplemente un estilo arquitectónico para las solicitudes y respuestas HTTP. Si el servidor REST de IndySoft está en funcionamiento y se han creado uno o varios scripts REST, IndySoft puede detectar solicitudes HTTP específicas y responder a ellas a través de este servicio.

He aquí un ejemplo muy sencillo. Supongamos que eres el propietario del dominio myurl.com y quieres permitir que una solicitud web concreta devuelva la fecha de vencimiento de la calibración de un activo específico. (¡Este es un ejemplo muy sencillo!). En primer lugar, se configuraría un script REST que se activara en respuesta a solicitudes HTTP específicas. Este script leería los parámetros necesarios en cada solicitud y, a continuación, generaría una respuesta HTTP. El nombre del script correspondería a la parte final de la URL de la solicitud. A continuación, instalarías o ejecutarías el servicio REST de IndySoft (apuntando a tu dominio myurl.com, que se ejecuta en un puerto específico, etc. Las funciones de scripting REST de IndySoft permiten acceder a todas las propiedades de las solicitudes HTTP (URL, puerto, IP, etc.), al tipo de solicitud («GET», «POST», «PUT», «DELETE»), a todos los encabezados, a todos los parámetros de consulta y al cuerpo del mensaje (ya sea como texto o como datos binarios). Existen funciones de script específicas para devolver cada uno de ellos. En nuestro ejemplo, supongamos que la solicitud web desde el lado del cliente se realiza íntegramente en la URL (en este ejemplo no se requiere ningún cuerpo de mensaje):

http://myurl.com:9001/IndyScripts/ReturnDueDate?Company=ABC+COMPANY&Id=ABC123

Así pues, en la URL del ejemplo anterior vemos que nuestro servidor REST de IndySoft funciona a través de HTTP (no HTTPS), que el dominio en el que está configurado es myurl.com y que el URI relativo (tal y como se ha configurado) es «IndyScripts». El nombre del script que se está ejecutando es «ReturnDueDate». Por último, se pasan dos parámetros de consulta: «Company» e «Id». Solo las solicitudes HTTP enviadas a «[http://myurl.com:9001/IndyScripts]» (http://myurl.com:9001/IndyScripts&#39;) llegarán al servidor REST de IndySoft. Además, solo se ejecutarán los scripts en aquellas solicitudes que vayan seguidas (en la URL) de un nombre de script, como en el caso de «[http://myurl.com:9001/IndyScripts/ReturnDueDate]» (http://myurl.com:9001/IndyScripts/ReturnDueDate&#39;), que ejecuta el script «ReturnDueDate». Por último, el script leerá los parámetros de la consulta (entre otros datos, según sea necesario) y responderá en consecuencia. A continuación se muestra un ejemplo del script del servidor REST:

sCompany = RequestQueryParameter("Company")

sID = RequestQueryParameter("Id")

if tdDoSQLRecords(1, "SELECT SCHED_DUE_DATE FROM SCHEDGI WHERE COMPANY = '" & sCompany & "' AND GAGE_SN = '" & sID & "' AND SCHED_TYPE = 'CALIBRATION'") then

sDueDate = tdFieldbyNameAsString(1, "SCHED_DUE_DATE")

ResponseStatusCode(700)

ResponseBodyAsText(sDueDate)

Else

sDueDate = ""

ResponseStatusCode(800)

ResponseBodyAsText(sDueDate)

End If

Este es un ejemplo muy sencillo. El script lee los parámetros de consulta de la URL correspondientes a «Company» e «Id». Ten en cuenta que los símbolos codificados en formato porcentual son sustituidos automáticamente por la función RequestQueryParameter (por ejemplo, «ABC+COMPANY» se devuelve como «ABC COMPANY»). A continuación, si se encuentra una fecha de vencimiento de CALIBRACIÓN para este activo, se devuelve dicha fecha en forma de texto, junto con un código de respuesta HTTP 700. Si no se encuentra ninguna fecha de vencimiento, se devuelve un texto vacío y un código de respuesta HTTP 800. En scripts más habituales, la respuesta de texto sería una página HTML completa. O bien, la respuesta incluiría un archivo XML en el cuerpo del mensaje de respuesta que proporcionaría más detalles sobre la transacción completada. Pero eso es lo básico: enviar una solicitud HTTP a una URL + URI relativa + script + parámetros opcionales. Incluye en esta solicitud encabezados opcionales y/o el cuerpo del mensaje. El script del servidor responde a las solicitudes válidas, lee los detalles del mensaje y envía la respuesta correspondiente. Las respuestas HTTP incluyen un código de respuesta y un cuerpo de mensaje en formato de texto o binario. El cliente HTTP debe ser capaz de responder adecuadamente (si la respuesta es un archivo HTML, se mostrará; si el cuerpo del mensaje contiene un PDF, se mostrará, etc.).

Configuración de IndySoftRESTServer
El primer paso (tras registrar «IndySoft REST Scripting» en la utilidad de registro de IndySoft) es configurar el servicio IndySoft REST en su servidor web. Este servicio responderá a todas las solicitudes web relacionadas con este dominio. Para abrir la pantalla de configuración, pulsa el botón «IndySoftRESTServer Setup» situado encima de la cuadrícula de scripts REST:

Configuración de IndySoftRESTServer

Configuración del servidor REST de IndySoft

Este cuadro de diálogo sirve para instalar o desinstalar el servicio REST de IndySoft, iniciar o detener el servicio, y configurar o guardar todos los ajustes relacionados. IMPORTANTE: Se necesitarán derechos de administrador de Windows si se utiliza este cuadro de diálogo para instalar o desinstalar el servicio, o para reservar automáticamente un espacio de nombres para el host o la URI. Asegúrate de cerrar y volver a iniciar IndySoftSyncOptions.exe seleccionando «Ejecutar como administrador» en Windows antes de continuar.

·Instalar servicio / Desinstalar servicio: el botón situado en la parte superior del cuadro de diálogo permite instalar o desinstalar el servicio, según corresponda. Ten en cuenta que se requieren los permisos de Windows adecuados para realizar esta acción. Una vez instalado, verás el servicio en la lista de servicios de Windows con el nombre «IndySoft REST Server». Una vez finalizada la instalación o la desinstalación, se cerrará el cuadro de diálogo. Nota: quizá te interese revisar el botón «Configuración avanzada» antes de instalar el servicio. Una vez instalado, el servicio se puede iniciar o detener mediante los botones situados en la parte inferior del cuadro de diálogo. Por supuesto, el servicio también se puede detener o iniciar directamente desde los Servicios de Windows.

·Puerto utilizado: Introduzca el puerto deseado para el servicio REST de IndySoft. Este puerto se puede especificar en la solicitud HTTP después del dominio del host, seguido de dos puntos (véase el ejemplo en el cuadro de diálogo).

·Usar HTTPS: marca esta casilla si prefieres las solicitudes HTTPS en lugar de HTTP. Si se utiliza HTTPS, es necesario especificar un certificado. Al guardar la configuración (al pulsar «Aceptar»), IndySoft te pedirá automáticamente que selecciones un certificado a través de Windows. Este proceso se llevará a cabo cuando IndySoft intente registrar el host especificado.

·Host: introduce el nombre de tu dominio de host para este servidor.Nota: Una vez guardada la configuración (al pulsar el botón «Aceptar»), IndySoft intentará registrar este espacio de nombres de URL automáticamente. El servidor REST de IndySoft se basa en hHTTPsys en modo kernel, lo que significa que el sistema operativo procesa todas las solicitudes HTTP. En esta arquitectura, el núcleo reenvía las solicitudes HTTP en función de la URL solicitada. Para que esto funcione, primero tenemos que reservar un espacio de nombres de URL. La reserva de espacio de nombres asigna los derechos sobre una parte del espacio de nombres de las URL HTTP a un grupo concreto de usuarios de Windows. Una reserva otorga a esos usuarios el derecho a crear servicios que escuchen en esa parte del espacio de nombres. Supongamos, pues, que, según la configuración especificada en este cuadro de diálogo, tu servidor funcionará en la dirección «[http://myurl.com:9001/IndyScripts/]» (http://myurl.com:9001/IndyScripts/&#39;). En ese caso, IndySoft intentará reservar ese espacio de nombres para garantizar que Windows acepte las solicitudes HTTP dirigidas a esas direcciones en lugar de rechazarlas. Si necesita configurar estas reglas manualmente, solicite la herramienta IndyHTTPConfig.exe al servicio de asistencia de IndySoft. Ten en cuenta que esta misma herramienta, IndyHTTPConfig.exe, ya está incluida en el servidor de aplicaciones de tres capas (en caso de que dicho servicio esté instalado en el mismo servidor).

·URI relativo: introduzca el nombre del URI relativo. Esta es la parte del espacio de nombres que sigue al host; por ejemplo, la parte «IndyScripts» de la URL completa «http://myurl.com:9001/IndyScripts/ScriptNameHere»

·Ejemplo: este texto de solo lectura añade los cuatro parámetros anteriores al formato requerido al realizar la solicitud del cliente. Ten en cuenta que la parte final de la URL incluirá una referencia al script específico (seguida de los parámetros de consulta opcionales). El pequeño botón situado a la derecha de este cuadro de edición abrirá la URL indicada. Tu navegador predeterminado gestionará la solicitud. Nota: este enlace web no está necesariamente completo; dado que normalmente se requieren parámetros de consulta adicionales o un cuerpo de mensaje, esto es solo un punto de partida.

·Inicio de sesión en el servidor: El servidor REST de IndySoft ejecuta los scripts mediante la conexión del cliente a la base de datos. Esto significa que algunos ajustes, como el correo electrónico, se adaptarán a la configuración del usuario y la ubicación. Por este motivo, es importante especificar un nombre de usuario que se utilizará para cargar esta configuración al iniciar el servidor REST de IndySoft. Se utilizará la ubicación predeterminada de este usuario.

·Cargar scripts previamente: Si se marca esta casilla, al iniciarse el servidor REST de IndySoft, todos los scripts se cargarán previamente en la memoria. Esto permite que cada solicitud web se ejecute un poco más rápido. El inconveniente es que, si se modifica el script (de IndySoft DataSync Utility...REST Scripts), será necesario detener y reiniciar el servicio para que los cambios en la funcionalidad surtan efecto. Si esta casilla no está marcada, el script se carga desde la base de datos con cada solicitud.

·Registrar todas las solicitudes: Esta opción normalmente solo se activa cuando se depura un script nuevo. Cuando esta opción está activada, todas las solicitudes se registran en la pestaña «Historial/Estado». El registro de solicitudes incluirá una lista completa de todas las propiedades, encabezados, parámetros de consulta y cuerpos de los mensajes disponibles para su consulta en los scripts. Los valores se anotarán en el registro con el mismo formato con el que se pueden consultar (si se desea) dentro del script.

·Configuración avanzada: Si lo desea, utilice este cuadro de diálogo para especificar las dependencias y las credenciales del servicio. Nota: estos ajustes solo se aplicarán al servicio una vez instalado

·Iniciar/Detener el servicio: utiliza los dos botones situados en la parte inferior izquierda del cuadro de diálogo para iniciar o detener el servidor REST de IndySoft.

Cuadro de scripts REST
Añadir/Editar/Eliminar script REST: utiliza estas opciones para añadir, editar o eliminar un script REST. Estas opciones solo están disponibles si «IndySoft REST Scripting» es un producto registrado. De lo contrario, se le pedirá un código de respuesta que solo puede obtener a través del servicio de asistencia de IndySoft.

Imprimir tabla de scripts REST: utiliza esta opción para imprimir rápidamente una lista actualizada de la tabla de scripts REST.

Ver solo el script REST: utiliza este botón para revisar el script REST seleccionado actualmente sin derechos de edición. Esta opción resulta útil si no tienes derechos de edición, pero necesitas comprobar el funcionamiento del script seleccionado.

Importar/exportar script REST: utiliza estas opciones para importar un script REST desde un archivo zip (tal y como se exportó anteriormente mediante la opción de exportación) o para exportar el script seleccionado actualmente a un archivo zip.

Configuración del servidor REST de IndySoft: utiliza esta opción para abrir el cuadro de diálogo de configuración del servidor REST.

Script REST: Añadir/Editar
·Nombre del script: el nombre único del script REST. Este nombre aparecerá en el historial de registros y en cualquier correo electrónico enviado desde el script o como respuesta a errores del script.

·Activo: indica si el script ha sido cargado o ejecutado por el servicio REST de IndySoft. El script solo se puede probar desde la pantalla IndySoftSyncOptions si esta opción no está marcada.

·VBScript/Pascal: cada script se puede escribir utilizando la sintaxis de VBScript o de Pascal

·Nombre codificado (para URL): se debe utilizar el nombre del script («Script Name», a la izquierda) para llamar a este script desde una solicitud HTTP web. Si el nombre del script contiene caracteres que no se pueden introducir en una URL, se debe utilizar la versión codificada del nombre del script (tal y como se muestra automáticamente aquí). Por ejemplo, el nombre del script «WEB SCRIPT» se codificaría como «WEB%20SCRIPT» en una URL.

·Descripción: una descripción más detallada del script

·Errores del script a: puede contener una o varias direcciones de correo electrónico. Estas personas recibirán automáticamente un correo electrónico si el script genera un error al ejecutarse. Ten en cuenta que estos errores están relacionados con la compilación del script, no son necesariamente errores del propio script que pudieran detectarse allí. Por ejemplo, si el script contiene errores de sintaxis, se enviará una notificación a estas direcciones de correo electrónico (ya que el script no se puede compilar). Pero si tu script carga un archivo XML, por ejemplo, y ese archivo XML tiene un formato incorrecto que devuelve un código de error, entonces la lógica de tu script puede que responda o no a ese código de error; eso depende del autor del script. Por lo tanto, si tu script lee el código de error, podrías llamar a la función SendEMail desde el propio script para responder a este error. Si deseas devolver estas direcciones de «Enviar errores a» desde el script, utiliza la función SendScriptErrorsTo.

A la derecha del script hay una pestaña titulada «Procedimientos/Funciones» que muestra a los usuarios los procedimientos y funciones disponibles. Los usuarios pueden arrastrar y soltar estas funciones o procedimientos en el área de script. La pestaña «Registro de depuración» registra cualquier error de sintaxis que se produzca durante la ejecución del script. Además, este texto del «Registro de depuración» se puede completar con notas de depuración desde el propio script llamando a la función DebugLog.

Si necesita ayuda o información sobre los procedimientos y funciones de script relacionados con REST, consulte los temas sobre «Funciones de script de REST» en la documentación de ayuda de IndySoft Custom Scripting. |