Mercurial > hg > orthanc-book

annotate Sphinx/source/users/advanced-rest.rst @ 224:02399e86f046

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
starting documentation of jobs
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 06 Mar 2019 07:41:49 +0100
parents
children ced9dbf86de8
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
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20 are tasks to be done by Orthanc. Jobs are first added to a queue of
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 pending tasks, and Orthanc will simultaneously a fixed number of jobs
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 (check out :ref:`configuration option <configuration>`
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23 ``ConcurrentJobs``). Once the jobs have been processed, they are tagged
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24 as successful or failed, and kept in a history (the size of this
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25 history is controlled by the ``JobsHistorySize`` option).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 Synchronous vs. asynchronous
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
30 Some calls to the REST API of Orthanc require time to be executed, and
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
31 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
32 includes the following URIs:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
33
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
34 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35 * Creating ZIP or media archives.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 * C-Move SCU (``/queries/.../retrieve``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 * C-Store SCU (``/modalities/.../store``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 * Sending to an Orthanc peer (``/peers/.../store``).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
39 * :ref:`Split/merge <split-merge>`.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 * Sending images using the :ref:`transfers accelerator <transfers>` plugin.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42 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
43 or an asynchronous mode:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 * **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
46 associated job. This is in general the default behavior.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47 * **Asynchronous calls** end immediately and return a handle to their
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48 associated job. It is up to the caller to monitor the end of the
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 execution by calling the jobs API.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 The choice between synchronous and asynchronous modes is done by
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 setting the `Synchronous` field (or indifferently `Asynchronous`
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 field) in the POST body of the call to the REST API. Note that the
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 :ref:`transfers accelerator <transfers>` only run in the asynchronous
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55 mode.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 Even if it is more complex to handle, the asynchronous mode is highly
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
58 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
59 seconds (typically, the creation of an archive or a network transfer).
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60 Indeed, this prevents timeouts in the HTTP protocol.
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
61
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 .. _pdf:
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67 PDF
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68 ---
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69
02399e86f046 starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 TODO