Mercurial > hg > orthanc-book
annotate Sphinx/source/users/advanced-rest.rst @ 735:e6386c012438 Orthanc-1.9.5
Orthanc 1.9.5
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Thu, 08 Jul 2021 11:34:06 +0200 |
parents | 8a247c645ac6 |
children | 97e6a0431c5e |
rev | line source |
---|---|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
1 .. _rest-advanced: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
2 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
3 Advanced features of the REST API |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
4 ================================= |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
5 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
6 .. contents:: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
7 :depth: 3 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
8 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
9 This section of the Orthanc Book is a complement to the description of |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
10 the :ref:`REST API of Orthanc <rest>`. It explains some advanced uses |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
11 of the API. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
12 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
13 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
14 .. _jobs: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
15 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
16 Jobs |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
17 ---- |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
18 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
19 Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs |
227 | 20 are high-level tasks to be processed by Orthanc. Jobs are first added |
21 to a queue of pending tasks, and Orthanc will simultaneously execute a | |
22 fixed number of jobs (check out :ref:`configuration option | |
23 <configuration>` ``ConcurrentJobs``). Once the jobs have been | |
24 processed, they are tagged as successful or failed, and kept in a | |
25 history (the size of this history is controlled by the | |
26 ``JobsHistorySize`` option). | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
27 |
227 | 28 By default, Orthanc saves the jobs into its database (check out the |
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. | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
34 |
227 | 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 | |
672
8bda16db46cf
SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
671
diff
changeset
|
41 .. _jobs-synchronicity: |
8bda16db46cf
SynchronousCMove: Synchronous vs. asynchronous C-MOVE SCP
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
671
diff
changeset
|
42 |
227 | 43 Synchronous vs. asynchronous calls |
44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
45 | |
46 Some calls to the REST API of Orthanc need time to be executed, and | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
47 thus result in adding a job to the processing queue. This notably |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 includes the following URIs: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
49 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
50 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
51 * Creating ZIP or media archives. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
52 * C-Move SCU (``/queries/.../retrieve``). |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
53 * C-Store SCU (``/modalities/.../store``). |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
54 * Sending to an Orthanc peer (``/peers/.../store``). |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
55 * :ref:`Split/merge <split-merge>`. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
56 * Sending images using the :ref:`transfers accelerator <transfers>` plugin. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
57 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
58 Such REST API calls can be configured to be executed in a synchronous |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
59 or an asynchronous mode: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
60 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
61 * **Synchronous calls** wait for the end of the execution of their |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
62 associated job. This is in general the default behavior. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
63 * **Asynchronous calls** end immediately and return a handle to their |
227 | 64 associated job. It is up to the caller to monitor the execution by |
65 calling the jobs API (e.g. to know whether the job has finished its | |
66 execution). | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
67 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
68 The choice between synchronous and asynchronous modes is done by |
227 | 69 setting the ``Synchronous`` field (or indifferently the |
70 ``Asynchronous`` field) in the POST body of the call to the REST | |
71 API. Note that the :ref:`transfers accelerator <transfers>` only runs | |
72 in asynchronous mode. | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
73 |
227 | 74 An integer number (possibly negative) can be specified in the |
75 ``Priority`` field of the POST body. Jobs with higher priority will be | |
76 executed first. By default, the priority is set to zero. | |
77 | |
78 Despite being more complex to handle, the asynchronous mode is highly | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
79 recommended for jobs whose execution time can last over a dozen of |
693
650100457193
SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
678
diff
changeset
|
80 seconds (typically, the creation of an archive if |
650100457193
SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
678
diff
changeset
|
81 ``SynchronousZipStream`` :ref:`configuration option <configuration>` |
650100457193
SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
678
diff
changeset
|
82 is set to ``false``, or a network transfer). Indeed, synchronous |
650100457193
SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
678
diff
changeset
|
83 calls can be affected by timeouts in the HTTP protocol if they last |
650100457193
SynchronousZipStream
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
678
diff
changeset
|
84 too long. |
227 | 85 |
86 | |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
253
diff
changeset
|
87 .. _jobs-monitoring: |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
253
diff
changeset
|
88 |
227 | 89 Monitoring jobs |
90 ^^^^^^^^^^^^^^^ | |
91 | |
92 .. highlight:: bash | |
93 | |
94 The list of all jobs can be retrieved as follows:: | |
95 | |
96 $ curl http://localhost:8042/jobs | |
97 [ "e0d12aac-47eb-454f-bb7f-9857931e2904" ] | |
98 | |
99 Full details about each job can be retrieved:: | |
100 | |
101 $ curl http://localhost:8042/jobs/e0d12aac-47eb-454f-bb7f-9857931e2904 | |
102 { | |
103 "CompletionTime" : "20190306T095223.753851", | |
104 "Content" : { | |
105 "Description" : "REST API", | |
106 "InstancesCount" : 1, | |
107 "UncompressedSizeMB" : 0 | |
108 }, | |
109 "CreationTime" : "20190306T095223.750666", | |
110 "EffectiveRuntime" : 0.001, | |
111 "ErrorCode" : 0, | |
112 "ErrorDescription" : "Success", | |
113 "ID" : "e0d12aac-47eb-454f-bb7f-9857931e2904", | |
114 "Priority" : 0, | |
115 "Progress" : 100, | |
116 "State" : "Success", | |
117 "Timestamp" : "20190306T095408.556082", | |
118 "Type" : "Archive" | |
119 } | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
120 |
227 | 121 Note that the ``/jobs?expand`` URI will retrieve this information in |
122 one single REST query. The ``Content`` field contains the parameters | |
123 of the job, and is very specific to the ``Type`` of job. | |
124 | |
125 The ``State`` field can be: | |
126 | |
127 * ``Pending``: The job is waiting to be executed. | |
128 * ``Running``: The job is being executed. The ``Progress`` field will | |
129 be continuously updated to reflect the progression of the execution. | |
130 * ``Success``: The job has finished with success. | |
131 * ``Failure``: The job has finished with failure. Check out the | |
132 ``ErrorCode`` and ``ErrorDescription`` fields for more information. | |
133 * ``Paused``: The job has been paused. | |
134 * ``Retry``: The job has failed internally, and has been scheduled for | |
735 | 135 re-submission after a delay. As of Orthanc 1.9.5, this feature is not |
227 | 136 used by any type of job. |
137 | |
138 In order to wait for the end of an asynchronous call, the caller will | |
139 typically have to poll the ``/jobs/...` URI (i.e. make periodic | |
140 calls), waiting for the ``State`` field to become ``Success`` or | |
141 ``Failure``. | |
142 | |
671
bc8fa2bf4cf7
asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
143 Note that the `integration tests of Orthanc |
735 | 144 <https://hg.orthanc-server.com/orthanc-tests/file/Orthanc-1.9.5/Tests/Toolbox.py>`__ |
671
bc8fa2bf4cf7
asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
145 give an example about how to monitor a job in Python using the REST |
bc8fa2bf4cf7
asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
146 API (cf. function ``MonitorJob()``). |
bc8fa2bf4cf7
asynchronous c-move
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
638
diff
changeset
|
147 |
227 | 148 |
322
c5226c5509ca
storage commitment scp
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
310
diff
changeset
|
149 .. _jobs-controlling: |
c5226c5509ca
storage commitment scp
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
310
diff
changeset
|
150 |
227 | 151 Interacting with jobs |
152 ^^^^^^^^^^^^^^^^^^^^^ | |
153 | |
154 Given the ID of some job, one can: | |
155 | |
156 * Cancel the job by POST-ing to ``/jobs/.../cancel``. | |
157 * Pause the job by POST-ing to ``/jobs/.../pause``. | |
158 * Resume a job in ``Paused`` state by POST-ing to ``/jobs/.../resume``. | |
159 * Retry a job in ``Failed`` state by POST-ing to ``/jobs/.../resubmit``. | |
160 | |
161 The related state machine is depicted in the `implementation notes | |
449 | 162 <https://hg.orthanc-server.com/orthanc/raw-file/default/OrthancServer/Resources/ImplementationNotes/JobsEngineStates.pdf>`__. |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
163 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
164 |
487
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
165 Example: Asynchronous generation of an archive |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
167 |
487
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
168 .. highlight:: bash |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
169 |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
170 Sucessful jobs are associated with a set of so-called "outputs" that |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
171 can be attached to the job. |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
172 |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
173 Here is a sample bash session to ask Orthanc to generate a ZIP |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
174 archive, then to download it locally:: |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
175 |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
176 $ curl http://localhost:8042/studies/27f7126f-4f66fb14-03f4081b-f9341db2-53925988/archive -d '{"Asynchronous":true}' |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
177 { |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
178 "ID" : "82cc02d1-03fe-41f9-be46-a308d16ea94a", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
179 "Path" : "/jobs/82cc02d1-03fe-41f9-be46-a308d16ea94a" |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
180 } |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
181 $ curl http://localhost:8042/jobs/82cc02d1-03fe-41f9-be46-a308d16ea94a |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
182 { |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
183 "CompletionTime" : "20200817T144700.401777", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
184 "Content" : { |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
185 "Description" : "REST API", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
186 "InstancesCount" : 232, |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
187 "UncompressedSizeMB" : 64 |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
188 }, |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
189 "CreationTime" : "20200817T144658.011824", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
190 "EffectiveRuntime" : 2.3879999999999999, |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
191 "ErrorCode" : 0, |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
192 "ErrorDescription" : "Success", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
193 "ID" : "82cc02d1-03fe-41f9-be46-a308d16ea94a", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
194 "Priority" : 0, |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
195 "Progress" : 100, |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
196 "State" : "Success", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
197 "Timestamp" : "20200817T144705.770825", |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
198 "Type" : "Archive" |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
199 } |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
200 $ curl http://localhost:8042/jobs/82cc02d1-03fe-41f9-be46-a308d16ea94a/archive > a.zip |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
201 |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
202 Note how we retrieve the content of the archive by accessing the |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
203 ``archive`` output of the job (check out the virtual method |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
204 ``IJob::GetOutput()`` from the `source code |
735 | 205 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.5/OrthancServer/Sources/ServerJobs/ArchiveJob.cpp>`__ |
487
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
206 of Orthanc). |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
207 |
516
416581db306e
sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
513
diff
changeset
|
208 Here is the corresponding sequence of commands to generate a DICOMDIR |
416581db306e
sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
513
diff
changeset
|
209 media:: |
416581db306e
sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
513
diff
changeset
|
210 |
416581db306e
sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
513
diff
changeset
|
211 $ curl http://localhost:8042/studies/27f7126f-4f66fb14-03f4081b-f9341db2-53925988/media -d '{"Asynchronous":true}' |
416581db306e
sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
513
diff
changeset
|
212 $ curl http://localhost:8042/jobs/6332be8a-0052-44fb-8cc2-ac959aeccad9/archive > a.zip |
416581db306e
sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
513
diff
changeset
|
213 |
735 | 214 As of Orthanc 1.9.5, only the creation of a ZIP or a DICOMDIR archive |
516
416581db306e
sample: asynchronous download of media archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
513
diff
changeset
|
215 produces such "outputs". |
487
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
216 |
13bb9af3df26
Example: Asynchronous generation of an archive
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
461
diff
changeset
|
217 |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
218 .. _pdf: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
219 |
310 | 220 Attaching PDF file as DICOM series |
221 ---------------------------------- | |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
222 |
226
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
223 Among many different types of data, DICOM files can be used to store |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
224 PDF files. The ``/tools/create-dicom`` URI can be used to upload a PDF |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
225 file to Orthanc. The following scripts perform such a *DICOM-ization*; |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
226 They convert the ``HelloWorld2.pdf`` file to base64, then perform a |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
227 ``POST`` request with JSON data containing the converted payload. |
225
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
228 |
545
931052bd5a53
explain the "Parent" field in "/tools/create-dicom" for PDF
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
528
diff
changeset
|
229 Importantly, the ``Parent`` field of the ``POST`` body can be set to |
931052bd5a53
explain the "Parent" field in "/tools/create-dicom" for PDF
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
528
diff
changeset
|
230 the :ref:`Orthanc identifier of some study <orthanc-ids>` in order to |
931052bd5a53
explain the "Parent" field in "/tools/create-dicom" for PDF
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
528
diff
changeset
|
231 attach the newly-created PDF series to the given parent study. |
931052bd5a53
explain the "Parent" field in "/tools/create-dicom" for PDF
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
528
diff
changeset
|
232 |
297
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
233 Using bash: |
227 | 234 |
297
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
235 .. code-block:: bash |
225
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
236 |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
237 # create the json data, with the BASE64 data embedded in it |
545
931052bd5a53
explain the "Parent" field in "/tools/create-dicom" for PDF
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
528
diff
changeset
|
238 (echo -n '{"Parent": "b6e8436b-c5835b7b-cecc9576-0483e165-ab5c710b", "Tags" : {"Modality" : "CT"}, "Content" : "data:application/pdf;base64,'; base64 HelloWorld2.pdf; echo '"}') > /tmp/foo |
225
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
239 |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
240 # upload it to Orthanc |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
241 cat /tmp/foo | curl -H "Content-Type: application/json" -d @- http://localhost:8042/tools/create-dicom |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
242 |
227 | 243 |
297
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
244 Using powershell: |
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
245 |
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
246 .. code-block:: perl |
225
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
247 |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
248 # create the BASE64 string data |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
249 $fileInBase64 = $([Convert]::ToBase64String((gc -Path "HelloWorld2.pdf" -Encoding Byte))) |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
250 |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
251 # create the json data |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
252 $params = @{Tags = @{PatientName = "Benjamino";Modality = "CT"};Content= "data:application/pdf;base64,$fileInBase64"} |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
253 |
376 | 254 # disabling the progress bar makes the Invoke-RestMethod call MUCH faster |
297
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
255 $ProgressPreference = 'SilentlyContinue' |
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
256 |
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
257 # upload it to Orthanc |
64d1ddab8246
Improved PDF creation Pwsh snippet + added Dicom instance upload example with
Benjamin Golinvaux <bgo@osimis.io>
parents:
290
diff
changeset
|
258 $reply = Invoke-RestMethod http://localhost:8042/tools/create-dicom -Method POST -Body ($params|ConvertTo-Json) -ContentType 'application/json' |
225
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
259 |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
260 # display the result |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
261 Write-Host "The instance can be retrieved in PDF at http://localhost:8042$($reply.Path)/pdf" |
ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
Benjamin Golinvaux <bgo@osimis.io>
parents:
224
diff
changeset
|
262 |
226
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
263 Please note that the ``/tools/create-dicom`` API call will return the |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
264 Orthanc instance ID of the newly created DICOM resource. |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
265 |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
266 You can use the ``/instances/.../pdf`` URI to retrieve an embedded PDF |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
267 file. |
228 | 268 |
269 | |
596 | 270 .. _private-tags: |
271 | |
272 Creating DICOM instance with private tags | |
273 ----------------------------------------- | |
274 | |
275 .. highlight:: json | |
276 | |
277 The ``/tools/create-dicom`` URI can be used to create DICOM instances | |
278 containing private tags. Those private tags must first be defined in | |
279 the ``Dictionary`` configuration option of Orthanc. Importantly, the | |
280 ``xxxx,0010`` tag must be defined to register the private creator, | |
281 where ``xxxx`` is the private group of interest. Here is a sample:: | |
282 | |
283 { | |
284 "Dictionary" : { | |
285 "0405,0010" : [ "LO", "Private data element", 1, 1, "RawDataStore" ], | |
286 "0405,1001" : [ "ST", "XML", 1, 1, "RawDataStore" ] | |
287 } | |
288 } | |
289 | |
290 Once Orthanc is started using this configuration file, it is possible | |
291 to create a DICOM instance using the following POST body on | |
292 ``/tools/create-dicom``:: | |
293 | |
294 { | |
295 "PrivateCreator" : "RawDataStore", | |
296 "Tags" : | |
297 { | |
298 "PatientName" : "Love^Sarah", | |
299 "PatientID" : "7", | |
300 "0405,0010" : "RawDataStore", | |
301 "0405,1001" : "<xml><test>Testing</test></xml>" | |
302 } | |
303 } | |
304 | |
228 | 305 |
306 .. _prometheus: | |
307 | |
308 Instrumentation with Prometheus | |
309 ------------------------------- | |
310 | |
311 .. highlight:: text | |
312 | |
313 Orthanc publishes its metrics according to the `text-based format of | |
314 Prometheus | |
315 <https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format>`__ | |
316 (check also the `OpenMetrics project <https://openmetrics.io/>`__), onto | |
317 the ``/tools/metrics-prometheus`` URI of the REST API. For instance:: | |
318 | |
319 $ curl http://localhost:8042/tools/metrics-prometheus | |
320 orthanc_count_instances 1 1551868380543 | |
321 orthanc_count_patients 1 1551868380543 | |
322 orthanc_count_series 1 1551868380543 | |
323 orthanc_count_studies 1 1551868380543 | |
324 orthanc_disk_size_mb 0.0135002136 1551868380543 | |
325 orthanc_jobs_completed 1 1551868380543 | |
326 orthanc_jobs_failed 0 1551868380543 | |
327 orthanc_jobs_pending 0 1551868380543 | |
328 orthanc_jobs_running 0 1551868380543 | |
329 orthanc_jobs_success 1 1551868380543 | |
330 orthanc_rest_api_active_requests 1 1551868380543 | |
331 orthanc_rest_api_duration_ms 0 1551868094265 | |
332 orthanc_storage_create_duration_ms 0 1551865919315 | |
333 orthanc_storage_read_duration_ms 0 1551865943752 | |
334 orthanc_store_dicom_duration_ms 5 1551865919319 | |
335 orthanc_uncompressed_size_mb 0.0135002136 1551868380543 | |
336 | |
337 | |
338 .. highlight:: bash | |
339 | |
340 Note that the collection of metrics can be statically disabled by | |
341 setting the :ref:`global configuration option <configuration>` | |
342 ``MetricsEnabled`` to ``false``, or dynamically disabled by PUT-ing | |
343 ``0`` on ``/tools/metrics``:: | |
344 | |
345 $ curl http://localhost:8042/tools/metrics | |
346 1 | |
347 $ curl http://localhost:8042/tools/metrics -X PUT -d '0' | |
348 $ curl http://localhost:8042/tools/metrics | |
349 0 | |
350 | |
351 | |
352 .. highlight:: yaml | |
353 | |
354 Here is a sample configuration for Prometheus (in the `YAML format | |
355 <https://en.wikipedia.org/wiki/YAML>`__):: | |
356 | |
357 scrape_configs: | |
358 - job_name: 'orthanc' | |
359 scrape_interval: 10s | |
360 metrics_path: /tools/metrics-prometheus | |
361 basic_auth: | |
362 username: orthanc | |
363 password: orthanc | |
364 static_configs: | |
365 - targets: ['192.168.0.2:8042'] | |
366 | |
367 .. highlight:: bash | |
368 | |
369 Obviously, make sure to adapt this sample with your actual IP | |
370 address. Thanks to Docker, you can easily start a Prometheus server by | |
371 writing this configuration to, say, ``/tmp/prometheus.yml``, then | |
372 type:: | |
373 | |
363
9c28eeab2db6
removed sudo from docker
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
359
diff
changeset
|
374 $ sudo run -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml --rm prom/prometheus:v2.7.0 |