annotate Sphinx/source/users/advanced-rest.rst @ 247:325dd3901547

ohif
author Sebastien Jodogne <s.jodogne@gmail.com>
date Sun, 19 May 2019 10:08:52 +0200
parents 972900443cf8
children a64197133114
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
20 are high-level tasks to be processed by Orthanc. Jobs are first added
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
21 to a queue of pending tasks, and Orthanc will simultaneously execute a
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
22 fixed number of jobs (check out :ref:`configuration option
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
23 <configuration>` ``ConcurrentJobs``). Once the jobs have been
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
24 processed, they are tagged as successful or failed, and kept in a
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
25 history (the size of this history is controlled by the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
26 ``JobsHistorySize`` option).
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
28 By default, Orthanc saves the jobs into its database (check out the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
29 ``SaveJobs`` option). If Orthanc is stopped then relaunched, the jobs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
30 whose processing was not finished are automatically put into the queue
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
31 of pending tasks. The command-line option ``--no-jobs`` can also be
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
32 used to prevent the loading of jobs from the database upon the launch
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
33 of Orthanc.
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
35 Note that the queue of pending jobs has a maximum size (check out the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
36 ``LimitJobs`` option). When this limit is reached, the addition of new
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
37 jobs is blocked until some job finishes.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
38
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
39
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
40
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
41 Synchronous vs. asynchronous calls
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
43
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
44 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
45 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
46 includes the following URIs:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 * Creating ZIP or media archives.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 * C-Move SCU (``/queries/.../retrieve``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 * C-Store SCU (``/modalities/.../store``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 * Sending to an Orthanc peer (``/peers/.../store``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 * :ref:`Split/merge <split-merge>`.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 * Sending images using the :ref:`transfers accelerator <transfers>` plugin.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 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
57 or an asynchronous mode:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 * **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
60 associated job. This is in general the default behavior.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61 * **Asynchronous calls** end immediately and return a handle to their
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
62 associated job. It is up to the caller to monitor the execution by
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
63 calling the jobs API (e.g. to know whether the job has finished its
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
64 execution).
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66 The choice between synchronous and asynchronous modes is done by
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
67 setting the ``Synchronous`` field (or indifferently the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
68 ``Asynchronous`` field) in the POST body of the call to the REST
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
69 API. Note that the :ref:`transfers accelerator <transfers>` only runs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
70 in asynchronous mode.
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
72 An integer number (possibly negative) can be specified in the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
73 ``Priority`` field of the POST body. Jobs with higher priority will be
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
74 executed first. By default, the priority is set to zero.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
75
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
76 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
77 recommended for jobs whose execution time can last over a dozen of
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78 seconds (typically, the creation of an archive or a network transfer).
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
79 Indeed, synchronous calls can be affected by timeouts in the HTTP
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
80 protocol if they last too long.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
81
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
82
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
83 Monitoring jobs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
84 ^^^^^^^^^^^^^^^
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
85
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
86 .. highlight:: bash
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
87
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
88 The list of all jobs can be retrieved as follows::
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
89
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
90 $ curl http://localhost:8042/jobs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
91 [ "e0d12aac-47eb-454f-bb7f-9857931e2904" ]
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
92
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
93 Full details about each job can be retrieved::
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
94
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
95 $ curl http://localhost:8042/jobs/e0d12aac-47eb-454f-bb7f-9857931e2904
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
96 {
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
97 "CompletionTime" : "20190306T095223.753851",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
98 "Content" : {
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
99 "Description" : "REST API",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
100 "InstancesCount" : 1,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
101 "UncompressedSizeMB" : 0
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
102 },
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
103 "CreationTime" : "20190306T095223.750666",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
104 "EffectiveRuntime" : 0.001,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
105 "ErrorCode" : 0,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
106 "ErrorDescription" : "Success",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
107 "ID" : "e0d12aac-47eb-454f-bb7f-9857931e2904",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
108 "Priority" : 0,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
109 "Progress" : 100,
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
110 "State" : "Success",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
111 "Timestamp" : "20190306T095408.556082",
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
112 "Type" : "Archive"
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
113 }
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
115 Note that the ``/jobs?expand`` URI will retrieve this information in
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
116 one single REST query. The ``Content`` field contains the parameters
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
117 of the job, and is very specific to the ``Type`` of job.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
118
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
119 The ``State`` field can be:
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
120
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
121 * ``Pending``: The job is waiting to be executed.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
122 * ``Running``: The job is being executed. The ``Progress`` field will
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
123 be continuously updated to reflect the progression of the execution.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
124 * ``Success``: The job has finished with success.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
125 * ``Failure``: The job has finished with failure. Check out the
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
126 ``ErrorCode`` and ``ErrorDescription`` fields for more information.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
127 * ``Paused``: The job has been paused.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
128 * ``Retry``: The job has failed internally, and has been scheduled for
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
129 re-submission after a delay. As of Orthanc 1.5.6, this feature is not
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
130 used by any type of job.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
131
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
132 In order to wait for the end of an asynchronous call, the caller will
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
133 typically have to poll the ``/jobs/...` URI (i.e. make periodic
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
134 calls), waiting for the ``State`` field to become ``Success`` or
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
135 ``Failure``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
136
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
137
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
138 Interacting with jobs
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
139 ^^^^^^^^^^^^^^^^^^^^^
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
140
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
141 Given the ID of some job, one can:
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
142
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
143 * Cancel the job by POST-ing to ``/jobs/.../cancel``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
144 * Pause the job by POST-ing to ``/jobs/.../pause``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
145 * Resume a job in ``Paused`` state by POST-ing to ``/jobs/.../resume``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
146 * Retry a job in ``Failed`` state by POST-ing to ``/jobs/.../resubmit``.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
147
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
148 The related state machine is depicted in the `implementation notes
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
149 <https://bitbucket.org/sjodogne/orthanc/raw/Orthanc-1.5.6/Resources/ImplementationNotes/JobsEngineStates.pdf>`__.
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
150
224
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
151
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
152
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
153
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
154 .. _pdf:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
155
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
156 PDF
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
157 ---
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
158
226
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
159 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
160 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
161 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
162 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
163 ``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
164
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
165 .. highlight:: bash
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
166
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
167 Using bash::
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
168
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
169 # create the json data, with the BASE64 data embedded in it
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
170 (echo -n '{"Tags" : {"PatientName" : "Benjamino", "Modality" : "CT"},"Content" : "data:application/pdf;base64,'; base64 HelloWorld2.pdf; echo '"}') > /tmp/foo
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
171
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
172 # 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
173 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
174
227
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
175 .. highlight:: powershell
08c47b8abeea jobs api
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 226
diff changeset
176
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
177 Using Powershell::
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
178
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
179 # 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
180 $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
181
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
182 # 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
183 $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
184
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
185 # upload it to Orthanc and convert the result to json
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
186 $reply = Invoke-WebRequest -Uri http://localhost:8042/tools/create-dicom -Method POST -Body ($params|ConvertTo-Json) -ContentType "application/json" | ConvertFrom-Json
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
187
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
188 # 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
189 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
190
226
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
191 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
192 Orthanc instance ID of the newly created DICOM resource.
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
193
eaae8d630277 proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 225
diff changeset
194 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
195 file.
228
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
196
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
197
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
198
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
199 .. _prometheus:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
200
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
201 Instrumentation with Prometheus
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
202 -------------------------------
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
203
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
204 .. highlight:: text
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
205
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
206 Orthanc publishes its metrics according to the `text-based format of
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
207 Prometheus
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
208 <https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format>`__
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
209 (check also the `OpenMetrics project <https://openmetrics.io/>`__), onto
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
210 the ``/tools/metrics-prometheus`` URI of the REST API. For instance::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
211
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
212 $ curl http://localhost:8042/tools/metrics-prometheus
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
213 orthanc_count_instances 1 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
214 orthanc_count_patients 1 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
215 orthanc_count_series 1 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
216 orthanc_count_studies 1 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
217 orthanc_disk_size_mb 0.0135002136 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
218 orthanc_jobs_completed 1 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
219 orthanc_jobs_failed 0 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
220 orthanc_jobs_pending 0 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
221 orthanc_jobs_running 0 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
222 orthanc_jobs_success 1 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
223 orthanc_rest_api_active_requests 1 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
224 orthanc_rest_api_duration_ms 0 1551868094265
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
225 orthanc_storage_create_duration_ms 0 1551865919315
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
226 orthanc_storage_read_duration_ms 0 1551865943752
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
227 orthanc_store_dicom_duration_ms 5 1551865919319
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
228 orthanc_uncompressed_size_mb 0.0135002136 1551868380543
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
229
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
230
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
231 .. highlight:: bash
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
232
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
233 Note that the collection of metrics can be statically disabled by
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
234 setting the :ref:`global configuration option <configuration>`
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
235 ``MetricsEnabled`` to ``false``, or dynamically disabled by PUT-ing
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
236 ``0`` on ``/tools/metrics``::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
237
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
238 $ curl http://localhost:8042/tools/metrics
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
239 1
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
240 $ curl http://localhost:8042/tools/metrics -X PUT -d '0'
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
241 $ curl http://localhost:8042/tools/metrics
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
242 0
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
243
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
244
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
245 .. highlight:: yaml
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
246
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
247 Here is a sample configuration for Prometheus (in the `YAML format
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
248 <https://en.wikipedia.org/wiki/YAML>`__)::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
249
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
250 scrape_configs:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
251 - job_name: 'orthanc'
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
252 scrape_interval: 10s
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
253 metrics_path: /tools/metrics-prometheus
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
254 basic_auth:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
255 username: orthanc
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
256 password: orthanc
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
257 static_configs:
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
258 - targets: ['192.168.0.2:8042']
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
259
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
260 .. highlight:: bash
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
261
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
262 Obviously, make sure to adapt this sample with your actual IP
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
263 address. Thanks to Docker, you can easily start a Prometheus server by
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
264 writing this configuration to, say, ``/tmp/prometheus.yml``, then
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
265 type::
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
266
972900443cf8 prometheus
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 227
diff changeset
267 $ sudo docker run -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml --rm prom/prometheus:v2.7.0