Saltar a contenido

Rules Webservice

Las reglas Webservice son reglas que funcionan de manera similar a webhooks, y pueden ser lanzadas desde prácticamente cualquier lugar de su red y la web.

Sus reglas Webservice se exponen automáticamente por el servidor Clarive bajo la URL http(s)://clariveserver/rule/[format]/[rulename]. Estos webservices son muy útiles para orquestar interacciones complejas en sus pipelines de DevOps y cadena de valor de entrega.

Las reglas Webservice reciben sus parámetros de la web, como la sub-ruta y devuelven datos que pueden traducirse a diferentes formatos. El formato de retorno depende del llamador para decidir usando la operación Webservice Response.

Datos de Solicitud

La solicitud llegará a la regla con las siguientes claves stash:

  • ${ws_params} - los parámetros GET o POST como un hash/objeto.

  • ${ws_body} - el cuerpo de solicitud sin procesar.

  • ${ws_headers} - el encabezado de solicitud como un hash/objeto. Los encabezados enviados dependen del agente de usuario (un navegador, cURL o cualquier librería de solicitud web de lenguaje). Los encabezados con claves pueden incluir Content-Type, Accept-Language y otros.

  • ${ws_arguments} - un array con las partes de la ruta URL detrás de la URL, es decir, para la URL https://clariveserver/rule/json/myrule/my/path la variable stash contendrá [ 'my', 'path'].

  • ${ws_uploads} - el manejador de archivos cargados de la solicitud.

  • ${ws_method} - el método de solicitud, GET, POST, PUT, etc.

  • ${ws_protocol} - el protocolo de solicitud, HTTP/1.0, HTTPS, etc.

  • ${WSURL} - el URI llamado por el solicitante, en el siguiente formato schema://[authority][path].

  • ${username} - el nombre de usuario del usuario autenticado.

  • ${ws_format} - el formato de datos solicitado: json, yaml, xml, raw.

De todos estos, ws_params son los datos más útiles. Para acceder a un cierto parámetro use la siguiente construcción de variable:

    ${ws_params.myvar}

Formatos de Datos de Respuesta

Los posibles formatos de datos de retorno de las reglas webservice son:

  • JSON
  • YAML
  • XML
  • Raw - simple texto plano o datos binarios devueltos por una Rule

El llamador establece el formato deseado en la URL de llamada, siguiendo el formato de URL del webservice:

    http(s)://clariveserver/rule/[json|yaml|xml|raw]/[rule-id]

El Content-Type de respuesta se establecerá de acuerdo con el formato de URL de llamada.

Desde la regla, la variable ${ws_format} se puede usar para determinar el formato de llamada solicitado por el usuario.

Crear una Respuesta

Para crear la respuesta del webservice, use la operación Webservice Response de la paleta.

La operación Webservice Response puede controlar qué encabezados, cookies y datos se devuelven del servidor al cliente solicitante.

Autenticación de Reglas Webservice

Los endpoints de webservice pueden ser autenticados o públicos.

Los endpoints públicos pueden ser accedidos por cualquiera. Nunca implemente webservices públicos que ejecuten operaciones sensibles. Los webservices públicos pueden ser útiles para reportar datos públicos como JSON, por ejemplo.

El método de autenticación es a través de una api-key. Las claves API se gestionan por usuario.

Asegurar Reglas Webservice

Además de usar reglas webservice autenticadas, recomendamos crear usuarios solo para webservice específicos usando la administración de usuarios, estableciendo sus permisos de modo que su alcance de seguridad esté limitado a los ámbitos permitidos, luego estableciendo la api-key para ese usuario para ser compartida con aplicaciones/desarrolladores externos específicos.

Manejo de Desconexión del Cliente

Cuando una regla webservice se llama desde un cliente externo (por ejemplo, curl) y el cliente se desconecta antes de que la regla termine (por ejemplo, el usuario presiona Ctrl-C), Clarive detecta automáticamente la desconexión y termina la ejecución de la regla. Esto evita que las reglas de larga duración desperdicien recursos del servidor cuando nadie está esperando la respuesta.

Excepción: Si la regla ha generado procesos hijos (por ejemplo, usando parallel_run en el DSL), se permitirá que la regla continúe ejecutándose en segundo plano incluso después de que el cliente se desconecte. Esto asegura que el trabajo bifurcado no se interrumpa.

Este comportamiento solo se aplica a reglas webservice e independientes llamadas vía HTTP. Las llamadas de reglas en formato SOAP no se ven afectadas.