Table Of Contents

Previous topic

vm.device.usb_passthrough_device

Next topic

Query Methods

Jobs

Tasks which require significant time to execute or process a significant amount of input or output are tagged as jobs. When a client connects to an endpoint marked as a job, they receive a job id from the endpoint. With this job id, the client can query the status of the job to see the progress and status. Errors are shown in the output, or the output contains the result returned by the endpoint on completion.

e.g. ws://truenas.domain/websocket

Example of connecting to endpoint marked as a job

Client connects to websocket endpoint and sends a connect message.

:::javascript {

“id”: “6841f242-840a-11e6-a437-00e04d680384”, “msg”: “method”, “method”: “catalog.sync_all”, “params”: []

}

Server answers with job_id.

:::javascript {

“msg”: “result”, “id”: “c0bb5952-fc60-232a-3d6c-a47961b771a5”, “result”: 53

}

Query Job Status

Job status can be queried with the core.get_jobs method.

Request:

:::javascript {

“id”: “d8e715be-6bc7-11e6-8c28-00e04d680384”, “msg”: “method”, “method”: “core.get_jobs”, “params”: [[[“id”, “=”, 53]]]

}

Response:

:::javascript {

“id”: “d8e715be-6bc7-11e6-8c28-00e04d680384”, “msg”: “result”, “result”: [{“id”: 53, “method”: “catalog.sync_all”, “arguments”: [], “logs_path”: null, “logs_excerpt”: null, “progress”: {“percent”: 100, “description”: “Syncing TEST catalog”, “extra”: null}, “result”: null, “error”: null, “exception”: null, “exc_info”: null, “state”: “SUCCESS”, “time_started”: {“$date”: 1571300596053}, “time_finished”: null}]

}

Uploading / Downloading Files

There are some jobs which require input or output as files which can be uploaded or downloaded.

Downloading a File

If a job gives a file as an output, this endpoint is to be used to download the output file.

Request:

:::javascript {

“id”: “d8e715be-6bc7-11e6-8c28-00e04d680384”, “msg”: “method”, “method”: “core.download”, “params”: [“config.save”, [{}], “freenas-FreeNAS-11.3-MASTER-201910090828-20191017122016.db”]

}

Response:

:::javascript {

“id”: “cdc8740a-336b-b0cd-b850-47568fe94223”, “msg”: “result”, “result”: [86, “/_download/86?auth_token=9WIqYg4jAYEOGQ4g319Bkr64Oj8CZk1VACfyN68M7hgjGTdeSSgZjSf5lJEshS8M”]

}

In the response, the first value 86 is the job id for config.save. This can be used to query the status of the job. The second value is a REST endpoint used to download the file.

The download endpoint has a special format:

http://system_ip/_download/{job_id}?auth_token={token}

job_id and token are parameters being passed.

core.download takes responsibility for providing the download URI with the job_id and token values.

Note: 1) Job output is not buffered, so execution would be blocked if a file download is not started. 2) File download must begin within 60 seconds or the job is canceled. 3) The file can only be downloaded once.

Uploading a File

Files can be uploaded via HTTP POST request only. The upload endpoint is:

http://system_ip/_upload

It expects two values as form data, data and file.

data is JSON-encoded data. It must be the first parameter provided and in this format:

::: json {

“method”: “config.upload”, “params”: []

}

file is the URI of the file to download.

This example uses curl,

Request:

curl -X POST -u root:freenas -H “Content-Type: multipart/form-data” -F ‘data={“method”: “config.upload”, “params”: []}’ -F “file=@/home/user/Desktop/config” http://system_ip/_upload/

Response:

{“job_id”: 20}