Mercurial > hg > orthanc-book

annotate Sphinx/source/users/advanced-rest.rst @ 226:eaae8d630277

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
proofreading of pdf
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 06 Mar 2019 10:44:38 +0100
parents ced9dbf86de8
children 08c47b8abeea
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:
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.