Mercurial > hg > orthanc-book

annotate Sphinx/source/users/advanced-rest.rst @ 225:ced9dbf86de8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
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
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.