Mercurial > hg > orthanc-book

comparison Sphinx/source/users/advanced-rest.rst @ 227:08c47b8abeea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
jobs api
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 06 Mar 2019 11:23:38 +0100
parents eaae8d630277
children 972900443cf8
comparison
equal deleted inserted replaced
226:eaae8d630277 227:08c47b8abeea
1 .. _rest-advanced: 1 .. _rest-advanced:
2 .. highlight:: bash
3 2
4 Advanced features of the REST API 3 Advanced features of the REST API
5 ================================= 4 =================================
6 5
7 .. contents:: 6 .. contents::
16 15
17 Jobs 16 Jobs
18 ---- 17 ----
19 18
20 Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs 19 Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs
21 are tasks to be done by Orthanc. Jobs are first added to a queue of 20 are high-level tasks to be processed by Orthanc. Jobs are first added
22 pending tasks, and Orthanc will simultaneously a fixed number of jobs 21 to a queue of pending tasks, and Orthanc will simultaneously execute a
23 (check out :ref:`configuration option <configuration>` 22 fixed number of jobs (check out :ref:`configuration option
24 ``ConcurrentJobs``). Once the jobs have been processed, they are tagged 23 <configuration>` ``ConcurrentJobs``). Once the jobs have been
25 as successful or failed, and kept in a history (the size of this 24 processed, they are tagged as successful or failed, and kept in a
26 history is controlled by the ``JobsHistorySize`` option). 25 history (the size of this history is controlled by the
26 ``JobsHistorySize`` option).
27 27
28 Synchronous vs. asynchronous 28 By default, Orthanc saves the jobs into its database (check out the
29 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 29 ``SaveJobs`` option). If Orthanc is stopped then relaunched, the jobs
30 whose processing was not finished are automatically put into the queue
31 of pending tasks. The command-line option ``--no-jobs`` can also be
32 used to prevent the loading of jobs from the database upon the launch
33 of Orthanc.
30 34
31 Some calls to the REST API of Orthanc require time to be executed, and 35 Note that the queue of pending jobs has a maximum size (check out the
36 ``LimitJobs`` option). When this limit is reached, the addition of new
37 jobs is blocked until some job finishes.
38
39
40
41 Synchronous vs. asynchronous calls
42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
43
44 Some calls to the REST API of Orthanc need time to be executed, and
32 thus result in adding a job to the processing queue. This notably 45 thus result in adding a job to the processing queue. This notably
33 includes the following URIs: 46 includes the following URIs:
34 47
35 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances. 48 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances.
36 * Creating ZIP or media archives. 49 * Creating ZIP or media archives.
44 or an asynchronous mode: 57 or an asynchronous mode:
45 58
46 * **Synchronous calls** wait for the end of the execution of their 59 * **Synchronous calls** wait for the end of the execution of their
47 associated job. This is in general the default behavior. 60 associated job. This is in general the default behavior.
48 * **Asynchronous calls** end immediately and return a handle to their 61 * **Asynchronous calls** end immediately and return a handle to their
49 associated job. It is up to the caller to monitor the end of the 62 associated job. It is up to the caller to monitor the execution by
50 execution by calling the jobs API. 63 calling the jobs API (e.g. to know whether the job has finished its
64 execution).
51 65
52 The choice between synchronous and asynchronous modes is done by 66 The choice between synchronous and asynchronous modes is done by
53 setting the `Synchronous` field (or indifferently `Asynchronous` 67 setting the ``Synchronous`` field (or indifferently the
54 field) in the POST body of the call to the REST API. Note that the 68 ``Asynchronous`` field) in the POST body of the call to the REST
55 :ref:`transfers accelerator <transfers>` only run in the asynchronous 69 API. Note that the :ref:`transfers accelerator <transfers>` only runs
56 mode. 70 in asynchronous mode.
57 71
58 Even if it is more complex to handle, the asynchronous mode is highly 72 An integer number (possibly negative) can be specified in the
73 ``Priority`` field of the POST body. Jobs with higher priority will be
74 executed first. By default, the priority is set to zero.
75
76 Despite being more complex to handle, the asynchronous mode is highly
59 recommended for jobs whose execution time can last over a dozen of 77 recommended for jobs whose execution time can last over a dozen of
60 seconds (typically, the creation of an archive or a network transfer). 78 seconds (typically, the creation of an archive or a network transfer).
61 Indeed, this prevents timeouts in the HTTP protocol. 79 Indeed, synchronous calls can be affected by timeouts in the HTTP
80 protocol if they last too long.
62 81
82
83 Monitoring jobs
84 ^^^^^^^^^^^^^^^
85
86 .. highlight:: bash
87
88 The list of all jobs can be retrieved as follows::
89
90 $ curl http://localhost:8042/jobs
91 [ "e0d12aac-47eb-454f-bb7f-9857931e2904" ]
92
93 Full details about each job can be retrieved::
94
95 $ curl http://localhost:8042/jobs/e0d12aac-47eb-454f-bb7f-9857931e2904
96 {
97 "CompletionTime" : "20190306T095223.753851",
98 "Content" : {
99 "Description" : "REST API",
100 "InstancesCount" : 1,
101 "UncompressedSizeMB" : 0
102 },
103 "CreationTime" : "20190306T095223.750666",
104 "EffectiveRuntime" : 0.001,
105 "ErrorCode" : 0,
106 "ErrorDescription" : "Success",
107 "ID" : "e0d12aac-47eb-454f-bb7f-9857931e2904",
108 "Priority" : 0,
109 "Progress" : 100,
110 "State" : "Success",
111 "Timestamp" : "20190306T095408.556082",
112 "Type" : "Archive"
113 }
114
115 Note that the ``/jobs?expand`` URI will retrieve this information in
116 one single REST query. The ``Content`` field contains the parameters
117 of the job, and is very specific to the ``Type`` of job.
118
119 The ``State`` field can be:
120
121 * ``Pending``: The job is waiting to be executed.
122 * ``Running``: The job is being executed. The ``Progress`` field will
123 be continuously updated to reflect the progression of the execution.
124 * ``Success``: The job has finished with success.
125 * ``Failure``: The job has finished with failure. Check out the
126 ``ErrorCode`` and ``ErrorDescription`` fields for more information.
127 * ``Paused``: The job has been paused.
128 * ``Retry``: The job has failed internally, and has been scheduled for
129 re-submission after a delay. As of Orthanc 1.5.6, this feature is not
130 used by any type of job.
131
132 In order to wait for the end of an asynchronous call, the caller will
133 typically have to poll the ``/jobs/...` URI (i.e. make periodic
134 calls), waiting for the ``State`` field to become ``Success`` or
135 ``Failure``.
136
137
138 Interacting with jobs
139 ^^^^^^^^^^^^^^^^^^^^^
140
141 Given the ID of some job, one can:
142
143 * Cancel the job by POST-ing to ``/jobs/.../cancel``.
144 * Pause the job by POST-ing to ``/jobs/.../pause``.
145 * Resume a job in ``Paused`` state by POST-ing to ``/jobs/.../resume``.
146 * Retry a job in ``Failed`` state by POST-ing to ``/jobs/.../resubmit``.
147
148 The related state machine is depicted in the `implementation notes
149 <https://bitbucket.org/sjodogne/orthanc/raw/Orthanc-1.5.6/Resources/ImplementationNotes/JobsEngineStates.pdf>`__.
150
63 151
64 152
65 153
66 .. _pdf: 154 .. _pdf:
67 155
72 PDF files. The ``/tools/create-dicom`` URI can be used to upload a PDF 160 PDF files. The ``/tools/create-dicom`` URI can be used to upload a PDF
73 file to Orthanc. The following scripts perform such a *DICOM-ization*; 161 file to Orthanc. The following scripts perform such a *DICOM-ization*;
74 They convert the ``HelloWorld2.pdf`` file to base64, then perform a 162 They convert the ``HelloWorld2.pdf`` file to base64, then perform a
75 ``POST`` request with JSON data containing the converted payload. 163 ``POST`` request with JSON data containing the converted payload.
76 164
165 .. highlight:: bash
166
77 Using bash:: 167 Using bash::
78 168
79 # create the json data, with the BASE64 data embedded in it 169 # create the json data, with the BASE64 data embedded in it
80 (echo -n '{"Tags" : {"PatientName" : "Benjamino", "Modality" : "CT"},"Content" : "data:application/pdf;base64,'; base64 HelloWorld2.pdf; echo '"}') > /tmp/foo 170 (echo -n '{"Tags" : {"PatientName" : "Benjamino", "Modality" : "CT"},"Content" : "data:application/pdf;base64,'; base64 HelloWorld2.pdf; echo '"}') > /tmp/foo
81 171
82 # upload it to Orthanc 172 # upload it to Orthanc
83 cat /tmp/foo | curl -H "Content-Type: application/json" -d @- http://localhost:8042/tools/create-dicom 173 cat /tmp/foo | curl -H "Content-Type: application/json" -d @- http://localhost:8042/tools/create-dicom
174
175 .. highlight:: powershell
84 176
85 Using Powershell:: 177 Using Powershell::
86 178
87 # create the BASE64 string data 179 # create the BASE64 string data
88 $fileInBase64 = $([Convert]::ToBase64String((gc -Path "HelloWorld2.pdf" -Encoding Byte))) 180 $fileInBase64 = $([Convert]::ToBase64String((gc -Path "HelloWorld2.pdf" -Encoding Byte)))