Mercurial > hg > orthanc-book
comparison Sphinx/source/users/advanced-rest.rst @ 227:08c47b8abeea
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))) |