Mercurial > hg > orthanc-book
annotate Sphinx/source/users/advanced-rest.rst @ 225:ced9dbf86de8
Added tutorial that shows how to upload and retrieve PDF files using the REST API
author | Benjamin Golinvaux <bgo@osimis.io> |
---|---|
date | Wed, 06 Mar 2019 08:13:01 +0100 |
parents | 02399e86f046 |
children | eaae8d630277 |
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 |
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
|
71 Among many different types of data, DICOM files can be used to store PDF files. The ``create-dicom`` API route can be used to upload a PDF file 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
|
72 |
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
|
73 The following scripts perform such a *dicomization* ; they convert the ``HelloWorld2.pdf`` file to base64, then perform a ``POST`` request with JSON data containing the converted payload. |
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
|
74 |
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
|
75 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
|
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 # 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
|
78 (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
|
79 |
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 # 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
|
81 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
|
82 |
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 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
|
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 # 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
|
86 $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
|
87 |
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 # 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
|
89 $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
|
90 |
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 # 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
|
92 $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
|
93 |
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 # 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
|
95 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
|
96 |
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 Please note that the `create-dicom` API call will return the Orthanc instance ID of the newly created DICOM resource. You can then use the ``http://localhost:8042/<INSTANCE-ID>/pdf`` route to request the stored file as PDF. |