Interface
===============

Interface REST
##################
A busca por job é provida por meio de uma interface REST.

A interface REST está especificada em OpenAPI (swagger) em conjunto com sua documentação:

* Especificação_
* Documentação_

.. _Especificação: https://git.tecgraf.puc-rio.br/soma/soma-job-history/blob/master/src/main/resources/search-api.yaml 

.. _documentação: swagger-spec.html

Nas seções seguintes são apresentados e explicados operadores do parâmetro *q* para busca de jobs.

Operadores do parâmetro *q*
############################

================== ====================
Operadores Básico  Descrição
\==                Igual
!=                 Não igual
=gt=    >          Maior que
=ge=    >=         Maior ou igual 
=lt=    <          Menor que
=le=    <=         Menor ou igual
=in=               Pertence
=out=              Não Pertence
================== ====================

========================= ===============
Operadores de Composição  Descrição
;                         AND lógico
,                         OR lógico
========================= ===============

Pode ser adicionado o caractere * antes ou depois de textos para operador *like*.
        
Tipo data/hora
############################

Formatos permitidos na requisição de campos do tipo data/hora:

* yyyy/MM/ddx
* yyyy/MM/dd HH:mmx
* yyyy/MM/dd HH:mm:ssx
* yyyy/MM/dd HH:mm:ss.SSSx

Onde **x** é o time zone (obrigatório na requisição) com os seguintes formatos permitidos:

* -hh
* -hhmm
* +hh
* +hhmm

Observação: o uso de operadores básicos para comparar valores do tipo data/hora considera o formato **yyyy/MM/dd HH:mm:ss.SSS** ao filtrar.

Time zone padrão da resposta:

* GMT0

Parâmetros com valor padrão para a busca
########################################

* *showParam*

   Descrição: Adiciona ao retorno os valores dos parâmetros do algoritmo

   Valor padrão: verdadeiro

* *limit*

   Descrição: Define o número de jobs retornados na busca

   Valor padrão: 1000

   Valor máximo permitido: 1000

Exemplos de query RSQL
##########################

Buscar job por descrição
****************************
* **RSQL:** ``description=="Teste Yade com batch"``
* **URL:** ``http://<host>/v1/jobs/history?q=description=="Teste Yade com batch"&offset=0&limit=20&locale=pt_BR``

Buscar job por owner
***********************
* **RSQL:** ``jobOwner=="adm*"``
* **URL:** ``http://<host>/v1/jobs/history?q=jobOwner=="adm*"&offset=0&limit=20&locale=pt_BR``

Buscar job por prioridade
****************************
* **RSQL:** ``priority==1``
* **URL:** ``http://<host>/v1/jobs/history?q=priority==1&offset=0&limit=20&locale=pt_BR``

Buscar job por nome do algoritmo
*********************************
* **RSQL:** ``algorithmName=="Teste_Progresso"``
* **URL:** ``http://<host>/v1/jobs/history?q=algorithmName==Teste_Progresso&offset=0&limit=20&locale=pt_BR``

Buscar job ordenadas pela data de submissão de modo ascendente
************************************************************************
* **RSQL:** ``attr=submissionTime&asc=true``
* **URL:** ``http://<host>/v1/jobs/history?offset=0&limit=20&attr=submissionTime&asc=true&locale=pt_BR``

Buscar job ordenadas pela data de submissão de modo não ascendente
************************************************************************
* **RSQL:** ``attr=submissionTime&asc=false``
* **URL:** ``http://<host>/v1/jobs/history?offset=0&limit=20&attr=submissionTime&asc=false&locale=pt_BR``

Buscar jobs executados em um determinada máquina e por um determinado dono
*****************************************************************************
* **RSQL:** ``executionMachine==40100;jobOwner=="admin"``
* **URL:** ``http://<host>/v1/jobs/history?q=executionMachine==40100;jobOwner=="admin"&offset=0&limit=20&locale=pt_BR``

Buscar job com prioridade ou que foram rodadas por um determinado dono
************************************************************************
* **RSQL:** ``priority==1,jobOwner=="admin"``
* **URL:** ``http://<host>/v1/jobs/history?q=priority==1,jobOwner=="admin"&offset=0&limit=20&locale=pt_BR``

Buscar jobs com descrição usando uma expressão regular
********************************************************
* **RSQL:** ``description==*MS2``
* **URL:** ``http://<host>/v1/jobs/history?q=(isDeleted==false);(description==*MS2)&offset=0&limit=20&locale=pt_BR``

Buscar jobs de um determinado algoritmo e que tenham sido cancelados
*********************************************************************
* **RSQL:** ``algorithmName=="Yade";exitStatus=="KILLED"``
* **Observação:** O valor de “exitStatus” precisa ser todo maiúsculo.
* **URL:** ``http://<host>/v1/jobs/history?q=algorithmName=="Yade";exitStatus=="KILLED"&offset=0&limit=20&locale=pt_BR``

Buscar jobs que possuam determinado parâmetro
**********************************************
* **RSQL:** ``paramLabel=="Sleeps"``
* **URL:** ``http://<host>/v1/jobs/history?q=paramLabel=="Sleeps"&offset=0&limit=20&locale=pt_BR``

Buscar jobs que possuam determinado valor para um determinado parâmetro
************************************************************************
* **RSQL:** ``(paramLabel=='Sleeps');(paramValue=='3')``
* **URL:** ``http://<host>/v1/jobs/history?q=(paramLabel=='Sleeps');(paramValue=='3')&offset=0&limit=20&locale=pt_BR``

Buscar jobs que possuam determinados valores para determinado parâmetro
************************************************************************
* **RSQL:** ``(paramLabel=='Sleeps');(paramValue=in=('3','1'))``
* **URL:** ``http://<host>/v1/jobs/history?q=(paramLabel=='Sleeps');(paramValue=in=('3','1'))&offset=0&limit=20&locale=pt_BR``

Buscar jobs que foram submetidos em uma determinada data/hora:
************************************************************************
* **RSQL:** ``submissionTime=='2019/06/12 21:24:25.342-0300'``
* **URL:** ``http://<host>/v1/jobs/history?q=submissionTime=='2019/06/12 21:24:25.342-0300'&offset=0&limit=20&locale=pt_BR``

        * Observação: para fazer requisição via URL o time zone é obrigatório sendo **-** o caractere para time zone negativo

Buscar jobs que finalizaram no intervalo de duas datas/horas:
************************************************************************
* **RSQL:** ``endTime=gt='2019/06/12 21:00+03';endTime=lt='2019/06/12 22:00+03'``
* **URL:** ``http://<host>/v1/jobs/history?q=endTime=gt='2019/06/12 21:00%2B03';endTime=lt='2019/06/12 22:00%2B03'&offset=0&limit=20&locale=pt_BR``

	* Observação: para fazer requisição via URL o time zone é obrigatório sendo **%2B** o encode para o caractere **+** referente ao time zone positivo

Estrutura do Job
####################

No caso do histórico de jobs, o JSON que define a estrutura básica de "jobs" sobre a qual a expressão RSQL é feita é o seguinte:

.. code-block:: json

   {  
            "jobId":"admi@test.CBNNGZHYE2",
            "groupId":"admi@test.CBNNGZHYE2",
            "projectId":"admin/testeYade",
            "jobOwner":"admin",
            "automaticallyMachineSelection":false,
            "submissionMachines":null,
            "numberOfProcesses":1,
            "numberOfProcessesByMachine":1,
            "submissionTime":"2019-06-12T21:24:25.342",
            "description":"test yade pela web",
            "priority":1,
            "multipleExecution":false,
            "jobType":"ALGORITHM",
            "numberOfAttempts":null,
            "executionMachine":"40100",
            "endTime":"2019-06-12T21:31:20.926",
            "exitCode":0,
            "guiltyNodeId":null,
            "exitStatus":"success",
            "cpuTime":0.0,
            "wallclockTime":412,
            "ramMemory":null,
            "statusHistory":[  
               {  
                  "status":"SCHEDULED",
                  "timestamp":"2019-06-12T21:24:25.342"
               },
               {  
                  "status":"UPLOADING",
                  "timestamp":"2019-06-12T21:24:27.334"
               },
               {  
                  "status":"EXECUTING",
                  "timestamp":"2019-06-12T21:24:27.358"
               },
               {  
                  "status":"DOWNLOADING",
                  "timestamp":"2019-06-12T21:31:20.815"
               },
               {  
                  "status":"FINISHED",
                  "timestamp":"2019-06-12T21:31:20.926"
               }
            ],
            "algorithms":[  
               {  
                  "algorithmId":"Yade",
                  "algorithmVersion":"5.0.0",
                  "algorithmName":"Yade",
                  "parameters":[  
                     {  
                        "id":86,
                        "parameterId":"working_dir",
                        "label":"Working Folder",
                        "type":"INPUT_FILE",
                        "value":[  
                           ".:DIRECTORY_TYPE"
                        ]
                     },
                     {  
                        "id":87,
                        "parameterId":"input_file",
                        "label":"Script File (.py)",
                        "type":"INPUT_FILE",
                        "value":[  
                           "teste/fiveParticles_v2.py:UNKNOWN"
                        ]
                     },
                     {  
                        "id":88,
                        "parameterId":"batch_run",
                        "label":"Enable multiple runs",
                        "type":"BOOLEAN",
                        "value":[  
                           "false"
                        ]
                     },
                     {  
                        "id":89,
                        "parameterId":"batch_file",
                        "label":"Parameter Table File",
                        "type":"INPUT_FILE",
                        "value":[  

                        ]
                     },
                     {  
                        "id":90,
                        "parameterId":"parallel_computation",
                        "label":"Enable parallel computation",
                        "type":"BOOLEAN",
                        "value":[  
                           "true"
                        ]
                     },
                     {  
                        "id":91,
                        "parameterId":"number_of_cores",
                        "label":"The number of cores for a job",
                        "type":"INTEGER",
                        "value":[  
                           "4"
                        ]
                     }
                  ]
               }
            ],
            "flowId":null,
            "flowVersion":null,
            "flowName":null,
            "lastModifiedTime":"2019-06-12T21:31:20.926"
         }
         

Possíveis valores de status:

* exitStatus
   * UNKNOWN
   * SUCCESS
   * EXECUTION_ERROR
   * JOB_IDENTIFIER_NOT_FOUND
   * UNEXPECTED_MACHINE_ERROR
   * PROJECT_NOT_FOUND
   * FAILED_SETUP_EXECUTION_ENVIRONMENT
   * NO_PERMISSION
   * NO_MACHINE_AVAILABLE
   * KILLED
   * LOST
   * UNDEFINED

* jobStatus
   * SCHEDULED
   * INIT
   * UPLOADING
   * QUEUED
   * EXECUTING
   * DOWNLOADING
   * FINISHED
   * UNKNOWN