Mercurial > hg > orthanc-book
annotate Sphinx/source/users/advanced-rest.rst @ 226:eaae8d630277
proofreading of pdf
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Wed, 06 Mar 2019 10:44:38 +0100 |
parents | ced9dbf86de8 |
children | 08c47b8abeea |
rev | line source |
---|---|
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
1 .. _rest-advanced: |
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
|
2 .. highlight:: bash |
224
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
3 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
4 Advanced features of the REST API |
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 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
7 .. contents:: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
8 :depth: 3 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
9 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
10 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
|
11 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
|
12 of the API. |
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 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
15 .. _jobs: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
16 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
17 Jobs |
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 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
20 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
|
21 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
|
22 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
|
23 (check out :ref:`configuration option <configuration>` |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
24 ``ConcurrentJobs``). Once the jobs have been processed, they are tagged |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
25 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
|
26 history is controlled by the ``JobsHistorySize`` option). |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
27 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
28 Synchronous vs. asynchronous |
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 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
31 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
|
32 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
|
33 includes the following URIs: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
34 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
35 * :ref:`Modifying and anonymizing <anonymization>` DICOM instances. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
36 * Creating ZIP or media archives. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
37 * C-Move SCU (``/queries/.../retrieve``). |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
38 * C-Store SCU (``/modalities/.../store``). |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
39 * Sending to an Orthanc peer (``/peers/.../store``). |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
40 * :ref:`Split/merge <split-merge>`. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
41 * Sending images using the :ref:`transfers accelerator <transfers>` plugin. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
42 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
43 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
|
44 or an asynchronous mode: |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
45 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
46 * **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
|
47 associated job. This is in general the default behavior. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 * **Asynchronous calls** end immediately and return a handle to their |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
49 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
|
50 execution by calling the jobs API. |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
51 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
52 The choice between synchronous and asynchronous modes is done by |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
53 setting the `Synchronous` field (or indifferently `Asynchronous` |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
54 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
|
55 :ref:`transfers accelerator <transfers>` only run in the asynchronous |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
56 mode. |
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 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
|
59 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
|
60 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
|
61 Indeed, this prevents timeouts in the HTTP protocol. |
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 |
02399e86f046
starting documentation of jobs
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
66 .. _pdf: |
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 PDF |
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 |
226
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
71 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
|
72 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
|
73 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
|
74 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
|
75 ``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
|
76 |
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
|
77 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
|
78 |
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
|
79 # 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
|
80 (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
|
81 |
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
|
82 # 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
|
83 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
|
84 |
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
|
85 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
|
86 |
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
|
87 # 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
|
88 $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
|
89 |
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
|
90 # 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
|
91 $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
|
92 |
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
|
93 # 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
|
94 $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
|
95 |
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
|
96 # 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
|
97 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
|
98 |
226
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
99 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
|
100 Orthanc instance ID of the newly created DICOM resource. |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
101 |
eaae8d630277
proofreading of pdf
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
225
diff
changeset
|
102 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
|
103 file. |