# BATCH API ## Gestión y monitoreo de trabajos Esta API permite controlar y compartir la información de procesos que se ejecutan desatendidos a petición de programas o usuarios. <img src="use-case-batch-api.svg" class="image-fluid"/> ### Generalidades * Trabajo. Es un proceso por lotes que ha sido iniciado por un usuario o sistema y que trasciende el ciclo de vida de la solicitud HTTP. * Trabajo vigente. Trabajo solicitado (status=0), en proceso (status=1) o en pausa (status=2) cuyo tiempo de vida previsto no se ha excedido. * Grupo de trabajos. Es un par Identificador y clave de API que permite administrar los trabajos * Token de trabajo. Es un identificador para poder consultar el estado de un trabajo Estados previstos: 0-Solicitado (estado inicial), 1-En proceso (estado inicial), 2-Pausado, 3-Terminado satisfactoriamente (estado terminal), 4-Terminado con errores (estado terminal) y 99-Cancelado (estado terminal) * Un trabajo no puede ponerse en pausa si ya ha concluido o ha sido cancelado * Un trabajo se considera terminado con errores si se excede su tiempo de vida * No puede cancelarse un trabajo que ya ha terminado * Si el nombre del programa está en la lista de programas del servicio, el estado inicial será "En proceso", en caso de no existir en dicha lista, el estado será "Solicitado" quedando al consumidor del servicio la responsabilidad de lanzarlo ## Administración de trabajos Se requiere el par de credenciales: Id o nombre del grupo de trabajos y clave de API ### Crear un trabajo #### Request ``` Method: POST URI: {base}/jobs/ Headers Content-Type: application/json;charset=utf-8 Authorization: Basic credenciales Payload { "program": "(Opcional) Nombre del programa que realiza el trabajo", "timeout": (Entero opcional que indica el tiempo de vigencia del trabajo), "progress_type": (Entero [0,1 o 2] opcional que indica la manera como se reporta el progreso), "steps": (Requerido solo si progress_type=2) entero que representa la cantidad de pasos o iteraciones si progress_type=2, "owner":"(Opcional) Id de usuario propietario del trabajo", "params": (opcional) Objeto con la información de inicio del trabajo } ``` * Credenciales = ```base64( jobsgroup:clave_de_api )``` #### Response ``` Content-Type: application/json;charset=utf-8 { "token":"Identificador del trabajo", "created":"Marca de tiempo del servidor", "group":"Id o nombre del grupo de trabajos", "program": "Nombre del trabajo", "timeout": (tiempo de vigencia del trabajo), "progress_type": (la manera como se reporta el progreso), "steps": (Cantidad de iteraciones si progress_type=2) "owner":"Id de usuario propietario del trabajo" } ``` ### Actualizar estado y progreso #### Request ``` Method: POST URI: {base}/jobs/{job_token}/ Headers Content-Type: application/json;charset=utf-8 Authorization: Basic credenciales payload { "note":"(Opcional, texto informativo", "new_status": (Entero opcional con el nuevo estado), "progress": (Decimal o entero opcional con el progreso del trabajo), "progress_type": (la manera como se reporta el progreso), "sender":"Identificador de quien envía el registro", "result": Objeto con el resultado del trabajo si new_status es un estado final } ``` * Credenciales = ```base64( jobsgroup:clave_de_api )``` #### Response ``` Content-Type: application/json;charset=utf-8 { "status":(Entero estado actual del trabajo), "progress":(Entero o decimal), "progress_type": (Entero que indica la forma de progreso) } ``` ### Solicitar cancelación, pausa y reanudación de trabajo #### Request ``` Method: POST URI: {base}/jobs/{job_token}/request/{action} Headers Authorization: Basic credenciales ``` * Credenciales = ```base64( jobsgroup:clave_de_api )``` * action es alguna de las siguientes: ```cancel```, ```pause```, ```play``` Respuesta ``` Content-Type: application/json;charset=utf-8 { "time_stamp":"Cadena de marca de tiempo de la solicitud" } ``` ### Consultar trabajos #### Request ``` Method: GET URI: {base}/jobs/?parametros Headers Authorization: Basic credenciales ``` * Credenciales = ```base64( jobsgroup:clave_de_api )``` Parametros. puede ser cualquier combinación de filtro de los siguientes: * owner - Identificador del usuario propietario, si no se indica se asume cualquier propietario * start_date - Fecha y hora de inicio del rango de tiempo, si no se indica, se asumen las 0 horas del día de hoy * end_date - Fecha y hora del final del rango de tiempo, si no se indica, se asume el momento actual * status - Estado del trabajo, si no se indica, se asume cualquier estado * program - Identificador del programa que agregó el trabajo, si no se indica se asume cualquier programa * limit - Cantidad de filas a recuperar, si no se indica, se asumen 100 #### Response ``` Content-Type: application/json;charset=utf-8 [ { "created":"Marca de tiempo de creación", "updated":"Marca de tiempo de última actualización", "start":"Marca de tiempo de inicio", "end":"Marca de tiempo de finalización", "program":"Programa que agregó el trabajo", "lifetime":Entero con la cantidad de segundos de vida, "timeout":Entero con la cantidad de segundos de vigencia, "progress":Entero o decimal con el progreso actual, "progress_type":Entero que indica la forma de indicar el progreso, "steps": (Cantidad de iteraciones si progress_type=2), "status":Entero que indica el estado actual del trabajo, "note":"Último mensaje de la bitácora", "sender":"Id de quien hizo la úlima actualización de estado", "requested_status": (opcional, entero que indica si se ha solicitado una cancelación, pausa o reanudación) "requested_status_tm": "Marca de tiempo de la solicitud de cancelación, pausa o reanudación" }, ... ] ``` ## Consultas de estado de trabajos No se requiere el par de credenciales administrativas, pero es necesario contar con un token de trabajo o un token de sesión válida (y la conexión a la que pertecen) ### Consultar estado de un trabajo #### Request ``` Method: GET URI: {base}/jobs/{job_token}/ ``` #### Response ``` Content-Type: application/json;charset=utf-8 { "created":"Marca de tiempo de creación", "updated":"Marca de tiempo de última actualización", "start":"Marca de tiempo de inicio", "end":"Marca de tiempo de finalización", "program":"Programa que agregó el trabajo", "lifetime":Entero con la cantidad de segundos de vida, "timeout":Entero con la cantidad de segundos de vigencia, "progress":Entero o decimal con el progreso actual, "progress_type":Entero que indica la forma de indicar el progreso, "steps": (Cantidad de iteraciones si progress_type=2), "status":Entero que indica el estado actual del trabajo, "note":"Último mensaje de la bitácora" "sender":"Id de quien hizo la úlima actualización de estado", "params": Objeto con los datos de entrada al proceso, "result": Objeto con los datos de resultado del proceso si status es un estado final, "requested_status": (opcional, entero que indica si se ha solicitado una cancelación, pausa o reanudación) "requested_status_tm": "Marca de tiempo de la solicitud de cancelación, pausa o reanudación" } ``` ### Consultar bitácora de un trabajo #### Request ``` Method: GET URI: {base}/jobs/{job_token}/log/ ``` #### Response ``` Content-Type: application/json;charset=utf-8 { "created":"Marca de tiempo de creación", "updated":"Marca de tiempo de última actualización", "start":"Marca de tiempo de inicio", "end":"Marca de tiempo de finalización", "program":"Programa que agregó el trabajo", "lifetime":Entero con la cantidad de segundos de vida, "timeout":Entero con la cantidad de segundos de vigencia, "progress":Entero o decimal con el progreso actual, "progress_type":Entero que indica la forma de indicar el progreso, "steps": (Cantidad de iteraciones si progress_type=2), "status":Entero que indica el estado actual del trabajo, "note":"Último mensaje de la bitácora" "sender":"Id de quien hizo la úlima actualización de estado", "params": Objeto con los datos de entrada al proceso, "result": Objeto con los datos de resultado del proceso si status es un estado final, "requested_status": (opcional, entero que indica si se ha solicitado una cancelación, pausa o reanudación) "requested_status_tm": "Marca de tiempo de la solicitud de cancelación, pausa o reanudación" "log": [ { "note":"nota", "progress":Entero o decimal con el progreso actual, "progress_type":Entero que indica la forma de indicar el progreso, "status":Entero que indica el estado actual del trabajo, "sender":"Id de quien hizo la actualización de estado" }, ... ] } ``` ### Consultar trabajos vigentes del usuario Recupera una lista de los trabajos vigentes que pertenecen al usuario cuya sesión se indica. Deben especificarse application y database para que el servicio valide la sesión y recupere el Id del usuario. #### Request ``` Method: GET URI: {base}/jobs/{application}/{database}/{token_sesión}/ ``` #### Response ``` Content-Type: application/json;charset=utf-8 [ { "created":"Marca de tiempo de creación", "updated":"Marca de tiempo de última actualización", "start":"Marca de tiempo de inicio", "end":"Marca de tiempo de finalización", "program":"Programa que agregó el trabajo", "lifetime":Entero con la cantidad de segundos de vida, "timeout":Entero con la cantidad de segundos de vigencia, "progress":Entero o decimal con el progreso actual, "progress_type":Entero que indica la forma de indicar el progreso, "steps": (Cantidad de iteraciones si progress_type=2), "status":Entero que indica el estado actual del trabajo, "note":"Último mensaje de la bitácora" "sender":"Id de quien hizo la úlima actualización de estado" }, ... ] ```