Mercurial > hg > orthanc-book
comparison Sphinx/source/users/advanced-rest.rst @ 224:02399e86f046
starting documentation of jobs
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Wed, 06 Mar 2019 07:41:49 +0100 |
parents | |
children | ced9dbf86de8 |
comparison
equal
deleted
inserted
replaced
223:9ccafca945d2 | 224:02399e86f046 |
---|---|
1 .. _rest-advanced: | |
2 | |
3 Advanced features of the REST API | |
4 ================================= | |
5 | |
6 .. contents:: | |
7 :depth: 3 | |
8 | |
9 This section of the Orthanc Book is a complement to the description of | |
10 the :ref:`REST API of Orthanc <rest>`. It explains some advanced uses | |
11 of the API. | |
12 | |
13 | |
14 .. _jobs: | |
15 | |
16 Jobs | |
17 ---- | |
18 | |
19 Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs | |
20 are tasks to be done by Orthanc. Jobs are first added to a queue of | |
21 pending tasks, and Orthanc will simultaneously a fixed number of jobs | |
22 (check out :ref:`configuration option <configuration>` | |
23 ``ConcurrentJobs``). Once the jobs have been processed, they are tagged | |
24 as successful or failed, and kept in a history (the size of this | |
25 history is controlled by the ``JobsHistorySize`` option). | |
26 | |
27 Synchronous vs. asynchronous | |
28 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
29 | |
30 Some calls to the REST API of Orthanc require time to be executed, and | |
31 thus result in adding a job to the processing queue. This notably | |
32 includes the following URIs: | |
33 | |
34 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances. | |
35 * Creating ZIP or media archives. | |
36 * C-Move SCU (``/queries/.../retrieve``). | |
37 * C-Store SCU (``/modalities/.../store``). | |
38 * Sending to an Orthanc peer (``/peers/.../store``). | |
39 * :ref:`Split/merge <split-merge>`. | |
40 * Sending images using the :ref:`transfers accelerator <transfers>` plugin. | |
41 | |
42 Such REST API calls can be configured to be executed in a synchronous | |
43 or an asynchronous mode: | |
44 | |
45 * **Synchronous calls** wait for the end of the execution of their | |
46 associated job. This is in general the default behavior. | |
47 * **Asynchronous calls** end immediately and return a handle to their | |
48 associated job. It is up to the caller to monitor the end of the | |
49 execution by calling the jobs API. | |
50 | |
51 The choice between synchronous and asynchronous modes is done by | |
52 setting the `Synchronous` field (or indifferently `Asynchronous` | |
53 field) in the POST body of the call to the REST API. Note that the | |
54 :ref:`transfers accelerator <transfers>` only run in the asynchronous | |
55 mode. | |
56 | |
57 Even if it is more complex to handle, the asynchronous mode is highly | |
58 recommended for jobs whose execution time can last over a dozen of | |
59 seconds (typically, the creation of an archive or a network transfer). | |
60 Indeed, this prevents timeouts in the HTTP protocol. | |
61 | |
62 | |
63 | |
64 | |
65 .. _pdf: | |
66 | |
67 PDF | |
68 --- | |
69 | |
70 TODO |