source: trunk/workshop/2013/first_service.rst @ 825

Last change on this file since 825 was 725, checked in by djay, 9 years ago

Fix issue with rst files displayed from Trac. Fix strings to be translated. Always use the same string in all messages.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 14.4 KB
Line 
1.. _first_service:
2
3Create your first ZOO Service
4=====================
5
6.. contents:: Table of Contents
7    :depth: 5
8    :backlinks: top
9
10Introduction
11---------------------
12
13In this part, you will create and publish from a simple ZOO Service named
14``Hello`` which will simply return a hello message containing the input value
15provided. It will be usefull to present in deeper details general concept on how ZOO-Kernel works and handles request.
16
17Service and publication process overview
18-----------------------------------
19
20Before starting developing a ZOO Service, you should remember that in
21ZOO-Project, a Service is a couple made of:
22
23 * a metadata file: a ZOO Service Configuration File (ZCFG) containing metadata
24   informations about a Service (providing informations about default / supported
25   inputs and outputs for a Service)
26 * a Services Provider: it depends on the programming language used, but for Python it
27   is a module and for JavaScript a script file.
28
29To publish your Service, which means make your ZOO Kernel aware of its presence,
30you should copy a ZCFG file in the directory where ``zoo_loader.cgi`` is located (in this workshop, ``/usr/lib/cgi-bin``).
31
32.. warning:: only the ZCFG file is required  for the Service to be considerate as
33    available. So if you don't get the Service Provider, obviously your Execute
34    request will fail as we will discuss later.
35
36Before publication, you should store your ongoing work, so you'll start by
37creating a directory to store the files of your Services Provider:
38
39.. code-block:: none
40   
41    mkdir -p /home/user/zoo-ws2013/ws_sp/cgi-env
42
43Once the ZCFG and the Python module are both ready, you can publish simply
44by copying the corresponding files in the same directory as the ZOO-Kernel.
45
46Create your first ZCFG file
47--------------------------
48
49You will start by creating the ZCFG file for the ``Hello`` Service. Edit the
50``/home/user/zoo-ws2013/ws_sp/cgi-env/Hello.zcfg`` file
51and add the following content:
52
53.. code-block:: none
54    :linenos:
55   
56    [Hello]
57     Title = Return a hello message.
58     Abstract = Create a welcome string.
59     processVersion = 2
60     storeSupported = true
61     statusSupported = true
62     serviceProvider = test_service
63     serviceType = Python
64     <DataInputs>
65      [name]
66       Title = Input string
67       Abstract = The string to insert in the hello message.
68       minOccurs = 1
69       maxOccurs = 1
70       <LiteralData>
71           dataType = string
72           <Default />
73       </LiteralData>
74     </DataInputs>
75     <DataOutputs>
76      [Result]
77       Title = The resulting string
78       Abstract = The hello message containing the input string
79       <LiteralData>
80           dataType = string
81           <Default />
82       </LiteralData>
83     </DataOutputs>
84
85.. note:: the name of the ZCFG file and the name between braket (here ``[Hello]``)
86    should be the same and correspond to the function name you will define in your
87    Services provider.
88
89As you can see in the ZOO Service Configuration File presented above it is divided into
90three distinct sections:
91  #. Main Metadata information (from line 2 to 8)
92  #. List of Inputs metadata information (from 9 line to 19)
93  #. List of Outputs metadata information (from line 20 to 28)
94
95You can get more informations about ZCFG from `the reference documentation
96<http://zoo-project.org/docs/services/zcfg-reference.html>`__.
97
98If you copy the ``Hello.zcfg`` file in the same directory as your ZOO Kernel
99then you will be able to request for DescribeProcess using the ``Hello``
100``Identifier``. The ``Hello`` service should also be listed from Capabilities
101document.
102
103.. code-block:: none
104   cp /home/user/zoo-ws2013/ws_sp/cgi-env/Hello.zcfg /usr/lib/cgi-bin
105
106Test requests
107---------------------
108
109In this section you will tests each WPS requests : GetCapabilities,
110DescribeProcess and Execute. Note that only GetCapabilities and DescribeProcess
111should work at this step.
112
113Test the GetCapabilities request
114.....................................................
115
116If you run the ``GetCapabilities`` request:
117
118.. code-block:: none
119   
120    http://localhost/cgi-bin/zoo_loader.cgi?request=GetCapabilities&service=WPS
121
122Now, you should find your Hello Service in a ``Process`` node in
123``ProcessOfferings``:
124
125.. code-block:: xml
126   
127    <wps:Process wps:processVersion="2">
128     <ows:Identifier>Hello</ows:Identifier>
129     <ows:Title>Return a hello message.</ows:Title>
130     <ows:Abstract>Create a welcome string.</ows:Abstract>
131    </wps:Process>
132
133Test the DescribeProcess request
134.....................................................
135
136You can access the ``ProcessDescription`` of the ``Hello`` service using the
137following ``DescribeProcess`` request:
138
139.. code-block:: none
140   
141    http://localhost/cgi-bin/zoo_loader.cgi?request=DescribeProcess&service=WPS&version=1.0.0&Identifier=Hello
142
143You should get the following response:
144
145.. code-block:: xml
146   
147    <wps:ProcessDescriptions xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsDescribeProcess_response.xsd" service="WPS" version="1.0.0" xml:lang="en-US">
148      <ProcessDescription wps:processVersion="2" storeSupported="true" statusSupported="true">
149        <ows:Identifier>Hello</ows:Identifier>
150        <ows:Title>Return a hello message.</ows:Title>
151        <ows:Abstract>Create a welcome string.</ows:Abstract>
152        <DataInputs>
153          <Input minOccurs="1" maxOccurs="1">
154            <ows:Identifier>name</ows:Identifier>
155            <ows:Title>Input string</ows:Title>
156            <ows:Abstract>The string to insert in the hello message.</ows:Abstract>
157            <LiteralData>
158              <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#string">string</ows:DataType>
159              <ows:AnyValue/>
160            </LiteralData>
161          </Input>
162        </DataInputs>
163        <ProcessOutputs>
164          <Output>
165            <ows:Identifier>Result</ows:Identifier>
166            <ows:Title>The resulting string</ows:Title>
167            <ows:Abstract>The hello message containing the input string</ows:Abstract>
168            <LiteralOutput>
169              <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#string">string</ows:DataType>
170            </LiteralOutput>
171          </Output>
172        </ProcessOutputs>
173      </ProcessDescription>
174    </wps:ProcessDescriptions>
175
176Test the Execute request
177.....................................................
178
179Obviously, you cannot run your Service because the Python file was not published
180yet. If you try the following ``Execute`` request:
181
182.. code-block:: none
183   
184    http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Hello&DataInputs=name=toto
185
186You should get an ExceptionReport similar to the one provided in the following,
187which is normal behavior:
188
189.. code-block:: xml
190
191    <ows:ExceptionReport xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xsi:schemaLocation="http://www.opengis.net/ows/1.1 http://schemas.opengis.net/ows/1.1.0/owsExceptionReport.xsd" xml:lang="en-US" version="1.1.0">
192      <ows:Exception exceptionCode="NoApplicableCode">
193        <ows:ExceptionText>Python module test_service cannot be loaded.</ows:ExceptionText>
194      </ows:Exception>
195    </ows:ExceptionReport>
196
197Implementing the Python Service
198-------------------------------
199
200General Principles
201.....................................................
202
203The most important thing you must know when implementing a new ZOO-Services
204using the Python language is that the function corresponding to your Service
205returns an integer value representing the status of execution
206(``SERVICE_FAILED`` [#f1]_ or ``SERVICE_SUCCEEDED`` [#f2]_) and takes three
207arguments (`Python dictionaries
208<http://docs.python.org/tutorial/datastructures.html#dictionaries>`__):
209
210  -  ``conf`` : the main environment configuration (corresponding to the main.cfg content)
211  - ``inputs`` : the requested / default inputs (used to access input values)
212  - ``outputs`` : the requested / default outputs (used to store computation result)
213
214.. note:: when your service return ``SERVICE_FAILED`` you can set
215    ``conf["lenv"]["message"]`` to add a personalized message in the ExceptionReport
216    returned by the ZOO Kernel in such case.
217
218You get in the following a sample ``conf`` value based on the ``main.cfg`` file you
219saw `before <using_zoo_from_osgeolivevm.html#zoo-kernel-configuration>`__.
220
221.. code-block:: javascript
222    :linenos:   
223
224    {
225      "main": {
226        language: "en-US",
227        lang: "fr-FR,ja-JP",
228        version: "1.0.0",
229        encoding: "utf-8",
230        serverAddress: "http://localhost/cgi-bin/zoo_loader.cgi",
231        dataPath: "/var/www/zoows-demo/map/data",
232        tmpPath: "/var/www/temp",
233        tmpUrl: "../temp",
234        cacheDir: "/var/www/temp/"
235      },
236      "identification": {
237        title: "The ZOO-Project WPS Server FOSS4G 2013 Nottingham Workshop",
238        keywords: "WPS,GIS,buffer",
239        abstract: "Demo version of Zoo-Project for OSGeoLiveDVD 2013. See http://www.zoo-project.org",
240        accessConstraints: "none",
241        fees: "None"
242      },
243      "provider": {
244        positionName: "Developer",
245        providerName: "ZOO-Project",
246        addressAdministrativeArea: "Lattes",
247        addressCountry: "fr",
248        phoneVoice: "False",
249        addressPostalCode: "34970",
250        role: "Dev",
251        providerSite: "http://www.zoo-project.org",
252        phoneFacsimile: "False",
253        addressElectronicMailAddress: "gerald.fenoy@geolabs.fr",
254        addressCity: "Denver",
255        individualName: "Gérald FENOY"
256      }
257
258In the following you get a sample outputs value passed to a Python or a JavaScript Service:
259
260.. code-block:: javascript
261    :linenos:   
262
263    {
264      'Result': {
265        'mimeType': 'application/json',
266        'inRequest': 'true',
267        'encoding': 'UTF-8'
268      }
269    }
270
271.. note:: the ``inRequest`` value is set internally by the ZOO-Kernel and can be    used to determine from the Service if the key was provided in the request.
272
273ZOO-Project provide a ZOO-API which was originally only available for
274JavaScript services, but thanks to the work of the ZOO-Project
275community, now you have also access to a ZOO-API when using
276the Python language. Thanks to the Python ZOO-API you don't have to remember anymore
277the value of SERVICE_SUCCEDED and SERVICE_FAILED, you
278have the capability to translate any string from your Python service
279by calling the ``_`` function (ie: ``zoo._('My string to
280translate')``) or to update the current status of a running service by
281using the ``update_status`` function the same way you use it from
282JavaScript or C services.
283
284The Hello Service
285.....................................................
286
287You can copy and paste the following into the
288``/home/user/zoo-ws2013/ws_sp/cgi-env/test_service.py`` file.
289
290.. code-block:: python
291   
292    import zoo
293    def Hello(conf,inputs,outputs):
294        outputs["Result"]["value"]=\
295                "Hello "+inputs["name"]["value"]+" from the ZOO-Project Python world !"
296        return zoo.SERVICE_SUCCEEDED
297
298Once you finish editing the file, you should copy it in the ``/usr/lib/cgi-bin`` directory:
299
300.. code-block:: none
301   
302    sudo cp /home/user/zoo-ws2013/ws_sp/cgi-env/* /usr/lib/cgi-bin
303
304
305Interracting with your service using Execute requests
306----------------------------------------------
307
308Now, you can request for Execute using the following basic url:
309
310.. code-block:: none
311   
312    http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Hello&DataInputs=name=toto
313
314You can request the WPS Server to return a XML WPS Response containing the result of
315your computation, requesting for ResponseDocument or you can access the data directly
316requesting for RawDataOutput.
317
318* Sample request using the RawDataOutput parameter:
319
320.. code-block:: none
321   
322    http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Hello&DataInputs=name=toto&RawDataOutput=Result
323
324* Sample request using the default ResponseDocument parameter:
325
326.. code-block:: none
327   
328    http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Hello&DataInputs=name=toto&ResponseDocument=Result
329
330When you are using ResponseDocument there is specific attribut you can use to ask
331the ZOO Kernel to store the result: ``asReference``. You can use the following example:
332
333.. code-block:: none
334   
335    http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Hello&DataInputs=name=toto&ResponseDocument=Result@asReference=true
336
337When computation take long time, the client should request the
338execution of a Service by setting both ``storeExecuteResponse`` and
339``status`` parameter to true to force asynchronous execution. This
340will make the ZOO-Kernel return, without waiting for the Service execution
341completion but after starting another ZOO-Kernel process responsible
342of the Service execution, a ResponseDocument containing a ``statusLocation``
343attribute which can be used to access the status of an ongoing service
344or the result when the process ended [#f3]_.
345
346.. code-block:: none
347   
348    http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Hello&DataInputs=name=toto&ResponseDocument=Result&storeExecuteResponse=true&status=true
349
350Conclusion
351-----------------
352
353Even if this first service was really simple it was useful to illustrate how the
354ZOO-Kernel fill ``conf``, ``inputs`` and ``outputs`` parameter prior to load
355and run your function service, how to write a ZCFG file, how to publish a Services
356Provider by placing the ZCFG and Python files in the same directory as the
357ZOO-Kernel, then how to interract with your service using both
358``GetCapabilities``, ``DescribeProcess`` and ``Execute`` requesr. We will see
359in the `next section <building_blocks_presentation.html>`__ how to write similar requests
360using the XML syntax.
361
362.. rubric:: Footnotes
363
364.. [#f1] ``SERVICE_FAILED=4``
365.. [#f2] ``SERVICE_SUCCEEDED=3``
366.. [#f3]  To get on-going status url in ``statusLocation``, you'll need to setup the `utils/status <http://www.zoo-project.org/trac/browser/trunk/zoo-project/zoo-services/utils/status>`_ Service. If you don't get this service available, the ZOO-Kernel will simply give the url to a flat XML file stored on the server which will contain, at the end of the execution, the result of the Service execution.
Note: See TracBrowser for help on using the repository browser.

Search

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png