⬆️External Request slot (Sending Requests to APIs from script)

Objeto e información general

La ranura de petición externa está diseñada para integrar el Agente con sistemas informáticos externos a través del protocolo HTTP (REST API o GraphQL, por ejemplo). Al procesar esta Ranura en el Script, se ejecuta una petición HTTP a la API del sistema externo, así como se recibe y procesa una respuesta a esta petición.

Creación y configuración de ranuras

Atributos de los Slot

La ranura de solicitud externa no contiene ajustes para la solicitud HTTP que envía; contiene una solicitud externa de recursos de la empresa, y la solicitud externa contiene todos los ajustes necesarios para enviar la solicitud y procesar la respuesta.

1. Nombre - el nombre de la Ranura, que se mostrará en el Árbol de Escenarios. La longitud máxima de un valor de campo es de 40 caracteres.

2. Solicitud - Solicitud externa de recursos de la empresa. Funciona la búsqueda incremental sin distinción entre mayúsculas y minúsculas de una consulta en la lista.

3. Botón MOSTRAR SOLICITUD EN UNA NUEVA PESTAÑA: al hacer clic en el botón, la solicitud externa seleccionada en el campo se abre en la siguiente pestaña del navegador.

Retraso en el envío de la solicitud

El usuario puede configurar una Petición Externa para retrasar el envío de una Petición Externa - esperar algún tiempo antes de que la petición sea enviada. Para ello, es necesario especificar una cabecera especial er-delay en las cabeceras de la petición en la sección Cabeceras con el valor igual al retraso en el envío de una solicitud externa en segundos. Requisitos para el valor er-delay:

• números enteros - de 0 a 60

• los números superiores a 60 se tratan como 60

• los números fraccionarios, los números negativos y los no numéricos se tratan como 0

⁠Ejemplos:

1. Falta la cabecera er-delay corresponde a una espera de 0 segundos

2. er-retraso: 10 corresponde a una espera de 10 segundos

3. er-delay: 0 corresponde a una espera de 0 segundos

4. er-delay: 100500 corresponde a una espera de 60 segundos

5. er-retraso: -100500 corresponde a una espera de 0 segundos

6. er-delay: valor no entero corresponde a una espera de 0 segundos

Solicitudes externas

Una Solicitud Externa es un objeto de Recursos de la Compañía, es decir, es accesible desde todos los Agentes de una determinada Compañía. Puede añadir, modificar, ver o eliminar una solicitud en la pestaña Solicitudes externas.

Funcionamiento de los Slot

Proceso de ejecución de la ranura de solicitud externa:

1. Definición de una Solicitud Externa a ejecutar;

2. Montaje de la URL final de una Solicitud Externa;

3. Colección de cabeceras de solicitud;

4. Montaje del cuerpo de la solicitud;

5. Enviar una solicitud;

6. Recepción de una respuesta y registro de Variables Contextuales.

   1. Tiempo de espera de una respuesta a una solicitud externa - 30 segundos

   2. Si el tamaño del cuerpo recibido en respuesta a una petición externa es superior a 5 KB, pero inferior a 100 KB, {"error": "el cuerpo recibido es superior a 5kb, puede analizarlo en la configuración de la petición externa, pero no se copiará en raw_response"} se escribe en raw_response;

   3. Si el tamaño del cuerpo recibido en respuesta a una solicitud externa es superior a 100 KB, el cuerpo se sustituye por uno vacío.

      1. Lo siguiente está escrito en raw_response: {"éxito":false, "error": "el cuerpo recibido es demasiado grande, se permite un máximo de 100kb"}.

   4. Si el tamaño del cuerpo recibido en respuesta a una solicitud externa no es superior a 100 KB, se intentará analizar la respuesta de acuerdo con la configuración de análisis de la pestaña Respuesta.

i. Si, al intentar parsear, fue posible encontrar un valor en la ruta dada, la Variable de Contexto correspondiente será creada\actualizada

ii. Si, al intentar parsear, no fue posible encontrar un valor en la ruta especificada, la Variable de Contexto correspondiente no es creada\actualizada.

e. Se intentará analizar una respuesta a una solicitud para cualquier código de respuesta de solicitud si se especifican los ajustes de análisis en la pestaña Respuesta

f. Cuando se procesa una respuesta a una solicitud, el código de respuesta de la solicitud se escribe en la variable response_status_code:

i. Si no es posible completar la solicitud, se escribirá el código 400

ii. Cuando expire el tiempo de espera de 30 segundos, se escribirá el código 408

iii. Si no hay respuesta del servidor, se registrará el código 499

g. En función de los resultados de la ejecución de la Solicitud Externa, se crea la variable request_success, que registra el resultado de la ejecución de la solicitud - éxito (True) o fracaso (False):

i. Si es imposible completar la solicitud o no hay respuesta del servidor, se escribirá False en request_success

ii. Si el código de respuesta es >=400, se escribirá False en request_success

iii. Si el código de respuesta es 200, pero no hay (incluyendo un {} BODY vacío) o un cuerpo inválido para este tipo de respuesta esperada, si se espera que la respuesta sea analizada (hay entradas en la pestaña Response), se escribirá False en request_success

iv. En los demás casos, se escribirá True en request_success: la solicitud se ha completado correctamente.

h. A partir del resultado de la ejecución de una Solicitud Externa, se crea la variable raw_response con el formato {"resultado de la ejecución de la solicitud", "cuerpo de la respuesta"}, ejemplo:{”success”:true,”temperature”:”-7.3”,”feels_like”:”-14.3 ”}.

i. La variable consta de dos partes:

1. La primera parte contiene el resultado de la solicitud "success":true o "success":false, que es un duplicado de la variable raw_response (el resultado depende de las condiciones descritas en el apartado 5)

2. La segunda parte contiene el cuerpo de la respuesta:

   1. Si tiene éxito, el cuerpo de la respuesta contiene el resultado del análisis especificado por la configuración de la pestaña Respuesta:

⁠b. Si no tiene éxito, el cuerpo de la respuesta contiene el texto del error recibido del sistema externo

ii. si no se ha podido enviar la solicitud al sistema externo, el valor del error se escribe en raw_response

iii. si se ha enviado correctamente una solicitud a un sistema externo, pero no se ha recibido ninguna respuesta, se escribe el valor no response en raw_response

i. Al recibir .xml de un sistema externo, la respuesta se escribe como una línea.

j. Al recibir un {} vacío BODY de un sistema externo, se escribe una cadena vacía en el cuerpo de la respuesta.