From ec8f99910224bf747edd7196b4462a773459ae6e Mon Sep 17 00:00:00 2001 From: Facundo Date: Thu, 10 Feb 2022 17:55:59 -0300 Subject: [PATCH] docs: translation (#22) * translation * landing page link in spanish --- docs/es/sync/README.md | 198 ++++++++++++++++++++++++++-- docs/es/sync/Rest_API_Response.json | 1 + docs/sync/README.md | 5 +- 3 files changed, 189 insertions(+), 15 deletions(-) create mode 100644 docs/es/sync/Rest_API_Response.json diff --git a/docs/es/sync/README.md b/docs/es/sync/README.md index 5c44913c..668bb823 100644 --- a/docs/es/sync/README.md +++ b/docs/es/sync/README.md @@ -1,37 +1,211 @@ -[![theeye.io](../../images/logo-theeye-theOeye-logo2.png)](https://theeye.io/index.html) +[![theeye.io](../images/logo-theeye-theOeye-logo2.png)](https://theeye.io/en/index.html) -# Sync API +# API Sync + +Ejecución sincrónica de tareas. ## URL **https://sync.theeye.io** +____ + +La ejecución de tareas individuales en TheEye es asincrónica por la naturaleza de los procesos. +Esto se debe a que las tareas en general son ejecutadas en lotes mediante el uso de "Queues". El tiempo y la complejidad varía en cada implementación. +Habitualmente no necesitamos esperar el resultado de forma instantanea. + +En algunos casos es necesario obtener el resultado de la ejecución de forma inmediata. +Este es aún común si necesitamos que las tareas se comporten como si fueran métodos de una API Rest. + +Este comportamiento puede ser logrado utilizando la API en modo Sync. +Cualquier tarea puede ser utilizada mediante la API Sync. Es necesario tener en cuenta que con tiempo de ejecución muy largos se pueden producir Timeouts o incluso el orquestador puede cortar la comunicación de forma repentina. + +Un tiempo de respuesta razonable no debe superar los 60 segundos de ejecución + +___ + + +## Rutas + +| Method | Path | Description | ACL | +| ---- | ----| ----| ----| +| POST | /${customer}/task/${id}/job | [Run task](#waiting-output) | user | + -La ejecución de tareas en TheEye es asincrónica por naturaleza. Esto significa que la tarea se va a ejecutar en segundo plano y el tiempo que tarda en completar varía. En general, no necesitamos esperar el resultado ya que lo podemos revisar cuando esté disponible. +## Argumentos -Pero hay casos que requieren que se ejecute la tarea y se espere al resultado. Este caso es común cuando se quiere conectar APIs o usar tareas que requieren interacción de usuario, entre otros escenarios. -Esto puede hacerse usando la API en modo `sync`. la única limitación es el timeout de ejecución de la tarea. Se recomienda configurar el timeout alrededor de los 60 segundos. El comportamiento de los clientes se puede editar pero por experiencia recomendamos evitarlo de no ser estríctamente necesario... +| Name | Values | Description | +| ---- | ---- | ---- | +| result | empty/null. is ignored | Result es la información informada por el Agente al finalizar la ejecución. En otros incluye execution log, output, lastline. | +| full | empty/null. is ignored | Responde con el document Job completo asociado a la ejecución. El mismo documento puede ser obtenido haciendo un GET a la API de jobs | +| parse | empty or a Number/Integer > 0 | El output de un job es almacenado en la base de datos como un Array de Strings, que si fuera encadenado serán argumentos de la siguiente tarea. La opción parse utilizara por defecto el índice 0 de este array de outputs y lo intentara interpretar como JSON. En algunos casos puede ser necesario utilizar un índice diferente al 0, sobre todo si se trabaja con outputs de tareas ya definidios en otras implementaciones. Usando parse=INDEX_NUM donde INDEX_NUM es un número entero del output. Si el índice no esta presente o no es posible interpretarlo se devuelve el output crudo | -## API Paths -| Metoodo | Dirección | Descripción | ACL | -| ------- | --------------------------- | --------------------------- | ---- | -| POST | /${customer}/task/${id}/job | [Run task](#esperar-por-el-output) | user | +## Respuesta -### NOTAS +Por defecto la API Sync responde con el output obtenido de la ejecución de la tarea. El output es lo que desde la interfaz se visualiza en la sección "output" del resultado de la ejecución. + +El output se almacena en la base de datos dentro del documento job. El job representa la instancia de ejecución de la tarea. + + +| State | HTTP Status Code | +| ---- | ---- | +| success | 200 | +| failure | 500 | + + +### NOTES + +* Por el momento solo es posible la ejecución de _Tareas Individuales_ . + + +____ -* Solo hay soporte para ejecución de **Tareas**. La ejecución de Workflows **NO es posible** en este momento. ## Ejemplos -### Esperar por el output +Puede descargar e importa [esta receta utilizada para todos los ejemplos](/sync/Rest_API_Response.json ":ignore") + + +### Esperando output ```bash + customer="" taskId="" token="" curl -s -X POST "https://sync.theeye.io/${customer}/task/${taskId}/job?access_token=${token}" | jq .output + + +``` + +### Ejemplo de resultado "failure" + + +```bash + +curl -i -X POST 'https://sync.theeye.io/${customer_id}/task/${task_id}/job?access_token=${token}' \ + --header 'content-type: application/json' \ + --data '{"task_arguments":[200]}' + +``` + + +```http + +HTTP/1.1 500 Internal Server Error +X-Powered-By: Express +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET,PUT,PATCH,POST,DELETE,OPTIONS +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: Origin, Accept, User-Agent, Accept-Charset, Cache-Control, Accept-Encoding, Content-Type, Authorization, Content-Length, X-Requested-With +Content-Type: application/json; charset=utf-8 +Content-Length: 135 +ETag: W/"87-+Fzdxc2Q7NsFIfhclF3lcqgSScY" +Date: Fri, 28 Jan 2022 16:59:54 GMT +Connection: keep-alive +Keep-Alive: timeout=5 + +["{\"message\":\"Validation Error. Invalid Argument Value\",\"statusCode\":418,\"name\":\"ClientError\",\"code\":\"\",\"status\":418}"] + + +``` + +### Ejemplo de resultado "success" + + +```bash + +curl -i -X POST 'https://sync.theeye.io/${customer_id}/task/${task_id}/job?access_token=${token}' \ + --header 'content-type: application/json' \ + --data '{"task_arguments":[100]}' + +``` + +```http + +HTTP/1.1 200 OK +X-Powered-By: Express +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET,PUT,PATCH,POST,DELETE,OPTIONS +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: Origin, Accept, User-Agent, Accept-Charset, Cache-Control, Accept-Encoding, Content-Type, Authorization, Content-Length, X-Requested-With +Content-Type: application/json; charset=utf-8 +Content-Length: 62 +ETag: W/"3e-Earn8PE7JwarkhTciq4Sn4inI3g" +Date: Fri, 28 Jan 2022 17:00:22 GMT +Connection: keep-alive +Keep-Alive: timeout=5 + +["{\"name\":\"tomer\",\"date\":\"2022-01-28T17:00:22.676Z\"}"] + ``` + + +### Ejemplo de "success" usando "parse" + + +Get the ID and replace in the requests below + +```bash + +curl -i -X POST 'https://sync.theeye.io/${customer_id}/task/${task_id}/job?parse&access_token=${token}' \ + --header 'content-type: application/json' \ + --data '{"task_arguments":[100]}' + +``` + + +```http + +HTTP/1.1 200 OK +X-Powered-By: Express +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET,PUT,PATCH,POST,DELETE,OPTIONS +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: Origin, Accept, User-Agent, Accept-Charset, Cache-Control, Accept-Encoding, Content-Type, Authorization, Content-Length, X-Requested-With +Content-Type: application/json; charset=utf-8 +Content-Length: 50 +ETag: W/"32-QGrCXrCY2sEcc1V/fL6omhdvPKY" +Date: Fri, 28 Jan 2022 16:26:41 GMT +Connection: keep-alive +Keep-Alive: timeout=5 + +{"name":"tomer","date":"2022-01-28T16:26:41.201Z"} + +``` + +### Ejemplo de "failure" usando "parse" + + +```bash + +curl -i -X POST 'https://sync.theeye.io/${customer_id}/task/${task_id}/job?parse&access_token=${token}' \ + --header 'content-type: application/json' \ + --data '{"task_arguments":[200]}' + +``` + + +```http + +HTTP/1.1 418 I'm a Teapot +X-Powered-By: Express +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET,PUT,PATCH,POST,DELETE,OPTIONS +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: Origin, Accept, User-Agent, Accept-Charset, Cache-Control, Accept-Encoding, Content-Type, Authorization, Content-Length, X-Requested-With +Content-Type: application/json; charset=utf-8 +Content-Length: 115 +ETag: W/"73-FBmPIgGdDNzn6NM27joxlSUMWp4" +Date: Fri, 28 Jan 2022 16:56:47 GMT +Connection: keep-alive +Keep-Alive: timeout=5 + +{"message":"Validation Error. Invalid Argument Value","statusCode":418,"name":"ClientError","code":"","status":418} + +``` + diff --git a/docs/es/sync/Rest_API_Response.json b/docs/es/sync/Rest_API_Response.json new file mode 100644 index 00000000..25787983 --- /dev/null +++ b/docs/es/sync/Rest_API_Response.json @@ -0,0 +1 @@ +{"task":{"order":0,"enable":true,"type":"script","public":false,"tags":[],"grace_time":0,"task_arguments":[{"id":1,"order":0,"type":"input","label":"number","value":"","help":"","readonly":false,"required":true,"multiple":false,"masked":false,"charsmin":0,"charsmax":0,"charset":null,"pattern":"","options":[]}],"arguments_type":"legacy","output_parameters":[],"register_body":false,"execution_count":83,"multitasking":true,"show_result":false,"assigned_users":[],"user_inputs":false,"user_inputs_members":[],"empty_viewers":false,"cancellable":true,"autoremove_completed_jobs_limit":5,"script_arguments":[{"id":1,"order":0,"type":"input","label":"number","value":"","help":"","readonly":false,"required":true,"multiple":false,"masked":false,"charsmin":0,"charsmax":0,"charset":null,"pattern":"","options":[]}],"logging":false,"_type":"ScriptTask","creation_date":"2022-01-28T13:01:43.355Z","last_update":"2022-01-28T16:56:46.292Z","env":{"NODE_ENV":""},"name":"Rest API Response","description":"","timeout":600000,"allows_dynamic_settings":false,"script_runas":"node %script%","template":null,"template_id":null,"source_model_id":"61f3e937c38201da80f96c27"},"file":{"order":0,"filename":"api.js","keyname":"api.js[ts:1643388995376]","mimetype":"text/javascript","extension":"js","size":2079,"description":"","md5":"824a8455060c66ebce1408efb52652dd","public":false,"tags":[],"source_model_id":"61f3e92cc38201da80f96c26","data":"Ly8gZXJyb3IgYW5kIG91dHB1dCBoYW5kbGVycyBtdXN0IGdvIGZpcnN0LgoKLyoqCiAqIEBwYXJhbSB7T2JqZWN0fQogKiBAcHJvcCB7TWl4ZWR9IGRhdGEKICogQHByb3Age0FycmF5fSBjb21wb25lbnRzCiAqIEBwcm9wIHtPYmplY3R9IG5leHQKICovCmNvbnN0IHN1Y2Nlc3NPdXRwdXQgPSAoeyBkYXRhLCBjb21wb25lbnRzLCBuZXh0IH0pID0+IHsKICAvLyBodHRwczovL2RvY3VtZW50YXRpb24udGhlZXllLmlvL2NvcmUtY29uY2VwdHMvc2NyaXB0cy8jcGFzc2luZy1hcmd1bWVudHMtaW4td29ya2Zsb3cKICBjb25zdCBvdXRwdXQgPSB7CiAgICBzdGF0ZTogInN1Y2Nlc3MiLAogICAgZGF0YSwKICAgIGNvbXBvbmVudHMsIC8vIGh0dHBzOi8vZG9jdW1lbnRhdGlvbi50aGVleWUuaW8vY29yZS1jb25jZXB0cy90YXNrcy9zY3JpcHRfdHlwZS8jY29tcG9uZW50cwogICAgbmV4dAogIH0KICBjb25zb2xlLmxvZyggSlNPTi5zdHJpbmdpZnkob3V0cHV0KSApCiAgcHJvY2Vzcy5leGl0KDApCn0KCi8qKgogKiBAcGFyYW0ge0Vycm9yfSBlcnIKICovCmNvbnN0IGZhaWx1cmVPdXRwdXQgPSAoZXJyKSA9PiB7CiAgY29uc29sZS5lcnJvcihlcnIpCiAgY29uc3Qgb3V0cHV0ID0gewogICAgc3RhdGU6ICJmYWlsdXJlIiwKICAgIGRhdGE6IGVycgogIH0KICBjb25zb2xlLmVycm9yKCBKU09OLnN0cmluZ2lmeShvdXRwdXQpICkKICBwcm9jZXNzLmV4aXQoMSkKfQoKcHJvY2Vzcy5vbigndW5oYW5kbGVkUmVqZWN0aW9uJywgKHJlYXNvbiwgcCkgPT4gewogIGNvbnNvbGUuZXJyb3IocmVhc29uLCAnVW5oYW5kbGVkIFJlamVjdGlvbiBhdCBQcm9taXNlJywgcCkKICBmYWlsdXJlT3V0cHV0KHJlYXNvbikKfSkKCnByb2Nlc3Mub24oJ3VuY2F1Z2h0RXhjZXB0aW9uJywgZXJyID0+IHsKICBjb25zb2xlLmVycm9yKGVyciwgJ1VuY2F1Z2h0IEV4Y2VwdGlvbiB0aHJvd24nKQogIGZhaWx1cmVPdXRwdXQoZXJyKQp9KQoKLy8gTm9kZUpzIGJvaWxlcnBsYXRlCmNvbnN0IG1haW4gPSBhc3luYyAoKSA9PiB7CiAgY29uc3QgYXJncyA9IHByb2Nlc3MuYXJndi5zbGljZSgyKQoKICBpZiAoYXJnc1swXSA+IDEwMCkgewogICAgdGhyb3cgbmV3IENsaWVudEVycm9yKCdWYWxpZGF0aW9uIEVycm9yLiBJbnZhbGlkIEFyZ3VtZW50IFZhbHVlJywgeyBzdGF0dXNDb2RlOiA0MTggfSkKICB9CgogIGNvbnN0IHJlc3VsdCA9IHsKICAgIGRhdGE6IHsKICAgICAgbmFtZTogInRvbWVyIiwKICAgICAgZGF0ZTogbmV3IERhdGUoKQogICAgfSwKICAgIGNvbXBvbmVudHM6IHsgInBvcHVwIjogIkhpIFdvcmxkISIgfSwKICAgIG5leHQ6IHt9CiAgfQoKICAvLyBhZGQgeW91ciBjb2RlIGhlcmUuCgogIHJldHVybiByZXN1bHQKfQoKY2xhc3MgQ2xpZW50RXJyb3IgZXh0ZW5kcyBFcnJvciB7CiAgY29uc3RydWN0b3IgKG1lc3NhZ2UsIG9wdGlvbnMpIHsKICAgIHN1cGVyKG1lc3NhZ2UgfHwgJ0ludmFsaWQgUmVxdWVzdCcpCiAgICBvcHRpb25zfHwob3B0aW9ucz17fSkKICAgIE9iamVjdC5hc3NpZ24odGhpcywgb3B0aW9ucykKICAgIHRoaXMubmFtZSA9IHRoaXMuY29uc3RydWN0b3IubmFtZQogICAgdGhpcy5jb2RlID0gb3B0aW9ucy5jb2RlIHx8ICcnCiAgICB0aGlzLnN0YXR1cyA9IG9wdGlvbnMuc3RhdHVzQ29kZSB8fCA0MDAKICB9CiAgCiAgdG9KU09OICgpIHsKICAgIGxldCBhbHQgPSB7fQogICAgbGV0IHN0b3JlS2V5ID0gZnVuY3Rpb24gKGtleSkgewogICAgICBpZiAoa2V5ID09PSAnc3RhY2snKSB7CiAgICAgICAgaWYgKHByb2Nlc3MuZW52Lk5PREVfRU5WICE9PSAncHJvZHVjdGlvbicpIHsKICAgICAgICAgIGFsdFtrZXldID0gdGhpc1trZXldCiAgICAgICAgfQogICAgICB9IGVsc2UgewogICAgICAgIGFsdFtrZXldID0gdGhpc1trZXldCiAgICAgIH0KICAgIH0KICAgIE9iamVjdC5nZXRPd25Qcm9wZXJ0eU5hbWVzKHRoaXMpLmZvckVhY2goc3RvcmVLZXksIHRoaXMpCiAgICByZXR1cm4gYWx0CiAgfQp9CgoKCi8vIGludm9rZSBtYWluIGFuZCBjYXB0dXJlIHJlc3VsdCBvdXRwdXQKbWFpbigpLnRoZW4oc3VjY2Vzc091dHB1dCkuY2F0Y2goZmFpbHVyZU91dHB1dCkK"}} \ No newline at end of file diff --git a/docs/sync/README.md b/docs/sync/README.md index 39a6ac21..de61208e 100644 --- a/docs/sync/README.md +++ b/docs/sync/README.md @@ -1,4 +1,4 @@ -[![theeye.io](../images/logo-theeye-theOeye-logo2.png)](https://theeye.io/en/index.html) +[![theeye.io](../../images/logo-theeye-theOeye-logo2.png)](https://theeye.io/index.html) # Sync API @@ -26,7 +26,6 @@ ___ ## Arguments -By default the sync api will respond with the final output of the task execution. when a job finishes the output value is parsed and then stored withing the job document in the output field. | Name | Values | Description | | ---- | ---- | ---- | @@ -37,7 +36,7 @@ By default the sync api will respond with the final output of the task execution ## Response -By default the response will be the raw task outputs without parsing +By default the sync api will respond with the final output of the task execution. when a job finishes the output value is parsed and then stored withing the job document in the output field. | State | HTTP Status Code | | ---- | ---- |