source: branches/PublicaMundi_David-devel/workshop/2013/_build/html/first_service.html @ 686

Last change on this file since 686 was 686, checked in by nbozon, 9 years ago

added workshop directory at root
File size: 39.9 KB
Line 
1
2
3<!DOCTYPE html>
4<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
5<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
6<head>
7  <meta charset="utf-8">
8  <meta name="viewport" content="width=device-width, initial-scale=1.0">
9 
10  <title>Creating your first ZOO Service &mdash; ZOO-Project 1.5 documentation</title>
11 
12  <link href="http://fonts.googleapis.com/css?family=Days+One" rel="stylesheet" type="text/css">
13 
14 
15
16 
17
18 
19 
20   
21      <link rel="search" type="application/opensearchdescription+xml" title="Search within ZOO-Project 1.5 documentation" href="_static/opensearch.xml"/>
22   
23
24 
25
26 
27 
28    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
29 
30
31 
32
33 
34    <link rel="top" title="ZOO-Project 1.5 documentation" href="index.html"/>
35        <link rel="next" title="Building blocks presentation - Using OGR and PgRouting based Web Services" href="building_blocks_presentation.html"/>
36        <link rel="prev" title="Configuration and ZOO-Kernel use" href="using_zoo_from_osgeolivevm.html"/> 
37
38 
39  <script src="_static/js/modernizr.min.js"></script>
40
41</head>
42
43<body class="wy-body-for-nav" role="document">
44
45  <div class="wy-grid-for-nav">
46
47   
48    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
49      <div class="wy-side-nav-search">
50       
51
52       
53          <a class="shrink" href="http://zoo-project.org"><img src="http://zoo-project.org/img/zoo-sun-logo.png" class="img-responsive sun" style="display: inline;"> ZOO</a>
54       
55
56       
57        </a>
58
59       
60<div role="search">
61  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
62    <input type="text" name="q" placeholder="Search docs" />
63    <input type="hidden" name="check_keywords" value="yes" />
64    <input type="hidden" name="area" value="default" />
65  </form>
66</div>
67
68       
69      </div>
70
71      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
72       
73         
74         
75              <ul class="current">
76<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a><ul>
77<li class="toctree-l2"><a class="reference internal" href="introduction.html#what-is-zoo">What is ZOO ?</a></li>
78<li class="toctree-l2"><a class="reference internal" href="introduction.html#how-does-zoo-works">How does ZOO works ?</a></li>
79<li class="toctree-l2"><a class="reference internal" href="introduction.html#what-are-we-going-to-do-in-this-workshop">What are we going to do in this workshop?</a></li>
80<li class="toctree-l2"><a class="reference internal" href="introduction.html#usefull-tips-for-reading">Usefull tips for reading</a></li>
81</ul>
82</li>
83<li class="toctree-l1"><a class="reference internal" href="using_zoo_from_osgeolivevm.html">Configuration and ZOO-Kernel use</a><ul>
84<li class="toctree-l2"><a class="reference internal" href="using_zoo_from_osgeolivevm.html#zoo-project-installation">ZOO-Project Installation</a></li>
85<li class="toctree-l2"><a class="reference internal" href="using_zoo_from_osgeolivevm.html#zoo-kernel-configuration">ZOO-Kernel Configuration</a></li>
86<li class="toctree-l2"><a class="reference internal" href="using_zoo_from_osgeolivevm.html#testing-the-zoo-installation-with-getcapabilities">Testing the ZOO installation with GetCapabilities</a></li>
87</ul>
88</li>
89<li class="toctree-l1 current"><a class="current reference internal" href="">Creating your first ZOO Service</a><ul>
90<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
91<li class="toctree-l2"><a class="reference internal" href="#service-and-publication-process-overview">Service and publication process overview</a></li>
92<li class="toctree-l2"><a class="reference internal" href="#creating-your-first-zcfg-file">Creating your first ZCFG file</a></li>
93<li class="toctree-l2"><a class="reference internal" href="#test-requests">Test requests</a></li>
94<li class="toctree-l2"><a class="reference internal" href="#implementing-the-python-service">Implementing the Python Service</a></li>
95<li class="toctree-l2"><a class="reference internal" href="#interracting-with-your-service-using-execute-requests">Interracting with your service using Execute requests</a></li>
96<li class="toctree-l2"><a class="reference internal" href="#conclusion">Conclusion</a></li>
97</ul>
98</li>
99<li class="toctree-l1"><a class="reference internal" href="building_blocks_presentation.html">Building blocks presentation - Using OGR and PgRouting based Web Services</a><ul>
100<li class="toctree-l2"><a class="reference internal" href="building_blocks_presentation.html#introduction">Introduction</a></li>
101<li class="toctree-l2"><a class="reference internal" href="building_blocks_presentation.html#services-provider-and-configuration-files">Services Provider and configuration files</a></li>
102<li class="toctree-l2"><a class="reference internal" href="building_blocks_presentation.html#the-buffer-service">The Buffer Service</a></li>
103<li class="toctree-l2"><a class="reference internal" href="building_blocks_presentation.html#the-intersection-service">The Intersection Service</a></li>
104<li class="toctree-l2"><a class="reference internal" href="building_blocks_presentation.html#the-differencepy-service">The DifferencePy Service</a></li>
105<li class="toctree-l2"><a class="reference internal" href="building_blocks_presentation.html#the-routing-and-profile-services">The Routing and Profile Services</a></li>
106<li class="toctree-l2"><a class="reference internal" href="building_blocks_presentation.html#conclusion">Conclusion</a></li>
107</ul>
108</li>
109<li class="toctree-l1"><a class="reference internal" href="js_services_chaining.html">Playing with buildign blocks - Creating JavaScript Web Services</a><ul>
110<li class="toctree-l2"><a class="reference internal" href="js_services_chaining.html#introduction">Introduction</a></li>
111<li class="toctree-l2"><a class="reference internal" href="js_services_chaining.html#zoo-api-overview">ZOO-API Overview</a></li>
112<li class="toctree-l2"><a class="reference internal" href="js_services_chaining.html#the-mask-service">The Mask Service</a></li>
113<li class="toctree-l2"><a class="reference internal" href="js_services_chaining.html#buffermask-service">BufferMask Service</a></li>
114<li class="toctree-l2"><a class="reference internal" href="js_services_chaining.html#bufferrequest-service">BufferRequest service</a></li>
115<li class="toctree-l2"><a class="reference internal" href="js_services_chaining.html#add-union-into-the-chain">Add Union into the chain</a></li>
116<li class="toctree-l2"><a class="reference internal" href="js_services_chaining.html#conclusion">Conclusion</a></li>
117</ul>
118</li>
119</ul>
120
121         
122       
123      </div>
124      &nbsp;
125    </nav>
126
127    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
128
129     
130      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
131        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
132        <a href="index.html">ZOO-Project</a>
133      </nav>
134
135
136     
137      <div class="wy-nav-content">
138        <div class="rst-content">
139          <div role="navigation" aria-label="breadcrumbs navigation">
140  <ul class="wy-breadcrumbs">
141
142    <li><a href="index.html"> Docs</a> &#8725; &#160;</li>
143     
144    <li>Creating your first ZOO Service</li>
145      <li class="wy-breadcrumbs-aside">
146       
147          <a href="_sources/first_service.txt" rel="nofollow"> View page source</a>
148       
149      </li>
150  </ul>
151  <hr/>
152</div>
153          <div role="main" class="document">
154           
155  <div class="section" id="creating-your-first-zoo-service">
156<span id="first-service"></span><h1><a class="toc-backref" href="#table-of-contents">Creating your first ZOO Service</a><a class="headerlink" href="#creating-your-first-zoo-service" title="Permalink to this headline"></a></h1>
157<div class="contents topic" id="table-of-contents">
158<p class="topic-title first">Table of Contents</p>
159<ul class="simple">
160<li><a class="reference internal" href="#creating-your-first-zoo-service" id="id4">Creating your first ZOO Service</a><ul>
161<li><a class="reference internal" href="#introduction" id="id5">Introduction</a></li>
162<li><a class="reference internal" href="#service-and-publication-process-overview" id="id6">Service and publication process overview</a></li>
163<li><a class="reference internal" href="#creating-your-first-zcfg-file" id="id7">Creating your first ZCFG file</a></li>
164<li><a class="reference internal" href="#test-requests" id="id8">Test requests</a><ul>
165<li><a class="reference internal" href="#test-the-getcapabilities-request" id="id9">Test the GetCapabilities request</a></li>
166<li><a class="reference internal" href="#test-the-describeprocess-request" id="id10">Test the DescribeProcess request</a></li>
167<li><a class="reference internal" href="#test-the-execute-request" id="id11">Test the Execute request</a></li>
168</ul>
169</li>
170<li><a class="reference internal" href="#implementing-the-python-service" id="id12">Implementing the Python Service</a><ul>
171<li><a class="reference internal" href="#general-principles" id="id13">General Principles</a></li>
172<li><a class="reference internal" href="#the-hello-service" id="id14">The Hello Service</a></li>
173</ul>
174</li>
175<li><a class="reference internal" href="#interracting-with-your-service-using-execute-requests" id="id15">Interracting with your service using Execute requests</a></li>
176<li><a class="reference internal" href="#conclusion" id="id16">Conclusion</a></li>
177</ul>
178</li>
179</ul>
180</div>
181<div class="section" id="introduction">
182<h2><a class="toc-backref" href="#table-of-contents">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
183<p>In this part, you will create and publish from a simple ZOO Service named
184<code class="docutils literal"><span class="pre">Hello</span></code> which will simply return a hello message containing the input value
185provided. It will be usefull to present in deeper details general concept on how ZOO-Kernel works and handles request.</p>
186</div>
187<div class="section" id="service-and-publication-process-overview">
188<h2><a class="toc-backref" href="#table-of-contents">Service and publication process overview</a><a class="headerlink" href="#service-and-publication-process-overview" title="Permalink to this headline"></a></h2>
189<p>Before starting developing a ZOO Service, you should remember that in
190ZOO-Project, a Service is a couple made of:</p>
191<blockquote>
192<div><ul class="simple">
193<li>a metadata file: a ZOO Service Configuration File (ZCFG) containing metadata
194informations about a Service (providing informations about default / supported
195inputs and outputs for a Service)</li>
196<li>a Services Provider: it depends on the programming language used, but for Python it
197is a module and for JavaScript a script file.</li>
198</ul>
199</div></blockquote>
200<p>To publish your Service, which means make your ZOO Kernel aware of its presence,
201you should copy a ZCFG file in the directory where <code class="docutils literal"><span class="pre">zoo_loader.cgi</span></code> is located (in this workshop, <code class="docutils literal"><span class="pre">/usr/lib/cgi-bin</span></code>).</p>
202<div class="admonition warning">
203<p class="first admonition-title">Warning</p>
204<p class="last">only the ZCFG file is required  for the Service to be considerate as
205available. So if you don&#8217;t get the Service Provider, obviously your Execute
206request will fail as we will discuss later.</p>
207</div>
208<p>Before publication, you should store your ongoing work, so you&#8217;ll start by
209creating a directory to store the files of your Services Provider:</p>
210<div class="highlight-none"><div class="highlight"><pre>mkdir -p /home/user/zoo-ws2013/ws_sp/cgi-env
211</pre></div>
212</div>
213<p>Once the ZCFG and the Python module are both ready, you can publish simply
214by copying the corresponding files in the same directory as the ZOO-Kernel.</p>
215</div>
216<div class="section" id="creating-your-first-zcfg-file">
217<h2><a class="toc-backref" href="#table-of-contents">Creating your first ZCFG file</a><a class="headerlink" href="#creating-your-first-zcfg-file" title="Permalink to this headline"></a></h2>
218<p>You will start by creating the ZCFG file for the <code class="docutils literal"><span class="pre">Hello</span></code> Service. Edit the
219<code class="docutils literal"><span class="pre">/home/user/zoo-ws2013/ws_sp/cgi-env/Hello.zcfg</span></code> file
220and add the following content:</p>
221<div class="highlight-none"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
222 2
223 3
224 4
225 5
226 6
227 7
228 8
229 9
23010
23111
23212
23313
23414
23515
23616
23717
23818
23919
24020
24121
24222
24323
24424
24525
24626
24727
24828</pre></div></td><td class="code"><div class="highlight"><pre>[Hello]
249 Title = Return a hello message.
250 Abstract = Create a welcome string.
251 processVersion = 2
252 storeSupported = true
253 statusSupported = true
254 serviceProvider = test_service
255 serviceType = Python
256 &lt;DataInputs&gt;
257  [name]
258   Title = Input string
259   Abstract = The string to insert in the hello message.
260   minOccurs = 1
261   maxOccurs = 1
262   &lt;LiteralData&gt;
263       dataType = string
264       &lt;Default /&gt;
265   &lt;/LiteralData&gt;
266 &lt;/DataInputs&gt;
267 &lt;DataOutputs&gt;
268  [Result]
269   Title = The resulting string
270   Abstract = The hello message containing the input string
271   &lt;LiteralData&gt;
272       dataType = string
273       &lt;Default /&gt;
274   &lt;/LiteralData&gt;
275 &lt;/DataOutputs&gt;
276</pre></div>
277</td></tr></table></div>
278<div class="admonition note">
279<p class="first admonition-title">Note</p>
280<p class="last">the name of the ZCFG file and the name between braket (here <code class="docutils literal"><span class="pre">[Hello]</span></code>)
281should be the same and correspond to the function name you will define in your
282Services provider.</p>
283</div>
284<p>As you can see in the ZOO Service Configuration File presented above it is divided into
285three distinct sections:</p>
286<blockquote>
287<div><ol class="arabic simple">
288<li>Main Metadata information (from line 2 to 8)</li>
289<li>List of Inputs metadata information (from 9 line to 19)</li>
290<li>List of Outputs metadata information (from line 20 to 28)</li>
291</ol>
292</div></blockquote>
293<p>You can get more informations about ZCFG from <a class="reference external" href="http://zoo-project.org/docs/services/zcfg-reference.html">the reference documentation</a>.</p>
294<p>If you copy the <code class="docutils literal"><span class="pre">Hello.zcfg</span></code> file in the same directory as your ZOO Kernel
295then you will be able to request for DescribeProcess using the <code class="docutils literal"><span class="pre">Hello</span></code>
296<code class="docutils literal"><span class="pre">Identifier</span></code>. The <code class="docutils literal"><span class="pre">Hello</span></code> service should also be listed from Capabilities
297document.</p>
298</div>
299<div class="section" id="test-requests">
300<h2><a class="toc-backref" href="#table-of-contents">Test requests</a><a class="headerlink" href="#test-requests" title="Permalink to this headline"></a></h2>
301<p>In this section you will tests each WPS requests : GetCapabilities,
302DescribeProcess and Execute. Note that only GetCapabilities and DescribeProcess
303should work at this step.</p>
304<div class="section" id="test-the-getcapabilities-request">
305<h3><a class="toc-backref" href="#table-of-contents">Test the GetCapabilities request</a><a class="headerlink" href="#test-the-getcapabilities-request" title="Permalink to this headline"></a></h3>
306<p>If you run the <code class="docutils literal"><span class="pre">GetCapabilities</span></code> request:</p>
307<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=GetCapabilities&amp;service=WPS
308</pre></div>
309</div>
310<p>Now, you should find your Hello Service in a <code class="docutils literal"><span class="pre">Process</span></code> node in
311<code class="docutils literal"><span class="pre">ProcessOfferings</span></code>:</p>
312<div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;wps:Process</span> <span class="na">wps:processVersion=</span><span class="s">&quot;2&quot;</span><span class="nt">&gt;</span>
313 <span class="nt">&lt;ows:Identifier&gt;</span>Hello<span class="nt">&lt;/ows:Identifier&gt;</span>
314 <span class="nt">&lt;ows:Title&gt;</span>Return a hello message.<span class="nt">&lt;/ows:Title&gt;</span>
315 <span class="nt">&lt;ows:Abstract&gt;</span>Create a welcome string.<span class="nt">&lt;/ows:Abstract&gt;</span>
316<span class="nt">&lt;/wps:Process&gt;</span>
317</pre></div>
318</div>
319</div>
320<div class="section" id="test-the-describeprocess-request">
321<h3><a class="toc-backref" href="#table-of-contents">Test the DescribeProcess request</a><a class="headerlink" href="#test-the-describeprocess-request" title="Permalink to this headline"></a></h3>
322<p>You can access the <code class="docutils literal"><span class="pre">ProcessDescription</span></code> of the <code class="docutils literal"><span class="pre">Hello</span></code> service using the
323following <code class="docutils literal"><span class="pre">DescribeProcess</span></code> request:</p>
324<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=DescribeProcess&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello
325</pre></div>
326</div>
327<p>You should get the following response:</p>
328<div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;wps:ProcessDescriptions</span> <span class="na">xmlns:ows=</span><span class="s">&quot;http://www.opengis.net/ows/1.1&quot;</span> <span class="na">xmlns:wps=</span><span class="s">&quot;http://www.opengis.net/wps/1.0.0&quot;</span> <span class="na">xmlns:xlink=</span><span class="s">&quot;http://www.w3.org/1999/xlink&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsDescribeProcess_response.xsd&quot;</span> <span class="na">service=</span><span class="s">&quot;WPS&quot;</span> <span class="na">version=</span><span class="s">&quot;1.0.0&quot;</span> <span class="na">xml:lang=</span><span class="s">&quot;en-US&quot;</span><span class="nt">&gt;</span>
329  <span class="nt">&lt;ProcessDescription</span> <span class="na">wps:processVersion=</span><span class="s">&quot;2&quot;</span> <span class="na">storeSupported=</span><span class="s">&quot;true&quot;</span> <span class="na">statusSupported=</span><span class="s">&quot;true&quot;</span><span class="nt">&gt;</span>
330    <span class="nt">&lt;ows:Identifier&gt;</span>Hello<span class="nt">&lt;/ows:Identifier&gt;</span>
331    <span class="nt">&lt;ows:Title&gt;</span>Return a hello message.<span class="nt">&lt;/ows:Title&gt;</span>
332    <span class="nt">&lt;ows:Abstract&gt;</span>Create a welcome string.<span class="nt">&lt;/ows:Abstract&gt;</span>
333    <span class="nt">&lt;DataInputs&gt;</span>
334      <span class="nt">&lt;Input</span> <span class="na">minOccurs=</span><span class="s">&quot;1&quot;</span> <span class="na">maxOccurs=</span><span class="s">&quot;1&quot;</span><span class="nt">&gt;</span>
335        <span class="nt">&lt;ows:Identifier&gt;</span>name<span class="nt">&lt;/ows:Identifier&gt;</span>
336        <span class="nt">&lt;ows:Title&gt;</span>Input string<span class="nt">&lt;/ows:Title&gt;</span>
337        <span class="nt">&lt;ows:Abstract&gt;</span>The string to insert in the hello message.<span class="nt">&lt;/ows:Abstract&gt;</span>
338        <span class="nt">&lt;LiteralData&gt;</span>
339          <span class="nt">&lt;ows:DataType</span> <span class="na">ows:reference=</span><span class="s">&quot;http://www.w3.org/TR/xmlschema-2/#string&quot;</span><span class="nt">&gt;</span>string<span class="nt">&lt;/ows:DataType&gt;</span>
340          <span class="nt">&lt;ows:AnyValue/&gt;</span>
341        <span class="nt">&lt;/LiteralData&gt;</span>
342      <span class="nt">&lt;/Input&gt;</span>
343    <span class="nt">&lt;/DataInputs&gt;</span>
344    <span class="nt">&lt;ProcessOutputs&gt;</span>
345      <span class="nt">&lt;Output&gt;</span>
346        <span class="nt">&lt;ows:Identifier&gt;</span>Result<span class="nt">&lt;/ows:Identifier&gt;</span>
347        <span class="nt">&lt;ows:Title&gt;</span>The resulting string<span class="nt">&lt;/ows:Title&gt;</span>
348        <span class="nt">&lt;ows:Abstract&gt;</span>The hello message containing the input string<span class="nt">&lt;/ows:Abstract&gt;</span>
349        <span class="nt">&lt;LiteralOutput&gt;</span>
350          <span class="nt">&lt;ows:DataType</span> <span class="na">ows:reference=</span><span class="s">&quot;http://www.w3.org/TR/xmlschema-2/#string&quot;</span><span class="nt">&gt;</span>string<span class="nt">&lt;/ows:DataType&gt;</span>
351        <span class="nt">&lt;/LiteralOutput&gt;</span>
352      <span class="nt">&lt;/Output&gt;</span>
353    <span class="nt">&lt;/ProcessOutputs&gt;</span>
354  <span class="nt">&lt;/ProcessDescription&gt;</span>
355<span class="nt">&lt;/wps:ProcessDescriptions&gt;</span>
356</pre></div>
357</div>
358</div>
359<div class="section" id="test-the-execute-request">
360<h3><a class="toc-backref" href="#table-of-contents">Test the Execute request</a><a class="headerlink" href="#test-the-execute-request" title="Permalink to this headline"></a></h3>
361<p>Obviously, you cannot run your Service because the Python file was not published
362yet. If you try the following <code class="docutils literal"><span class="pre">Execute</span></code> request:</p>
363<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto
364</pre></div>
365</div>
366<p>You should get an ExceptionReport similar to the one provided in the following,
367which is normal behavior:</p>
368<div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;ows:ExceptionReport</span> <span class="na">xmlns:ows=</span><span class="s">&quot;http://www.opengis.net/ows/1.1&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xmlns:xlink=</span><span class="s">&quot;http://www.w3.org/1999/xlink&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://www.opengis.net/ows/1.1 http://schemas.opengis.net/ows/1.1.0/owsExceptionReport.xsd&quot;</span> <span class="na">xml:lang=</span><span class="s">&quot;en-US&quot;</span> <span class="na">version=</span><span class="s">&quot;1.1.0&quot;</span><span class="nt">&gt;</span>
369  <span class="nt">&lt;ows:Exception</span> <span class="na">exceptionCode=</span><span class="s">&quot;NoApplicableCode&quot;</span><span class="nt">&gt;</span>
370    <span class="nt">&lt;ows:ExceptionText&gt;</span>Python module test_service cannot be loaded.<span class="nt">&lt;/ows:ExceptionText&gt;</span>
371  <span class="nt">&lt;/ows:Exception&gt;</span>
372<span class="nt">&lt;/ows:ExceptionReport&gt;</span>
373</pre></div>
374</div>
375</div>
376</div>
377<div class="section" id="implementing-the-python-service">
378<h2><a class="toc-backref" href="#table-of-contents">Implementing the Python Service</a><a class="headerlink" href="#implementing-the-python-service" title="Permalink to this headline"></a></h2>
379<div class="section" id="general-principles">
380<h3><a class="toc-backref" href="#table-of-contents">General Principles</a><a class="headerlink" href="#general-principles" title="Permalink to this headline"></a></h3>
381<p>The most important thing you must know when implementing a new ZOO-Services
382using the Python language is that the function corresponding to your Service
383returns an integer value representing the status of execution
384(<code class="docutils literal"><span class="pre">SERVICE_FAILED</span></code> <a class="footnote-reference" href="#f1" id="id1">[1]</a> or <code class="docutils literal"><span class="pre">SERVICE_SUCCEEDED</span></code> <a class="footnote-reference" href="#f2" id="id2">[2]</a>) and takes three
385arguments (<a class="reference external" href="http://docs.python.org/tutorial/datastructures.html#dictionaries">Python dictionaries</a>):</p>
386<blockquote>
387<div><ul class="simple">
388<li><code class="docutils literal"><span class="pre">conf</span></code> : the main environment configuration (corresponding to the main.cfg content)</li>
389<li><code class="docutils literal"><span class="pre">inputs</span></code> : the requested / default inputs (used to access input values)</li>
390<li><code class="docutils literal"><span class="pre">outputs</span></code> : the requested / default outputs (used to store computation result)</li>
391</ul>
392</div></blockquote>
393<div class="admonition note">
394<p class="first admonition-title">Note</p>
395<p class="last">when your service return <code class="docutils literal"><span class="pre">SERVICE_FAILED</span></code> you can set
396<code class="docutils literal"><span class="pre">conf[&quot;lenv&quot;][&quot;message&quot;]</span></code> to add a personalized message in the ExceptionReport
397returned by the ZOO Kernel in such case.</p>
398</div>
399<p>You get in the following a sample <code class="docutils literal"><span class="pre">conf</span></code> value based on the <code class="docutils literal"><span class="pre">main.cfg</span></code> file you
400saw <a class="reference external" href="using_zoo_from_osgeolivevm.html#zoo-kernel-configuration">before</a>.</p>
401<div class="highlight-javascript"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
402 2
403 3
404 4
405 5
406 6
407 7
408 8
409 9
41010
41111
41212
41313
41414
41515
41616
41717
41818
41919
42020
42121
42222
42323
42424
42525
42626
42727
42828
42929
43030
43131
43232
43333</pre></div></td><td class="code"><div class="highlight"><pre><span class="p">{</span>
434  <span class="s2">&quot;main&quot;</span><span class="o">:</span> <span class="p">{</span>
435    <span class="nx">language</span><span class="o">:</span> <span class="s2">&quot;en-US&quot;</span><span class="p">,</span>
436    <span class="nx">lang</span><span class="o">:</span> <span class="s2">&quot;fr-FR,ja-JP&quot;</span><span class="p">,</span>
437    <span class="nx">version</span><span class="o">:</span> <span class="s2">&quot;1.0.0&quot;</span><span class="p">,</span>
438    <span class="nx">encoding</span><span class="o">:</span> <span class="s2">&quot;utf-8&quot;</span><span class="p">,</span>
439    <span class="nx">serverAddress</span><span class="o">:</span> <span class="s2">&quot;http://localhost/cgi-bin/zoo_loader.cgi&quot;</span><span class="p">,</span>
440    <span class="nx">dataPath</span><span class="o">:</span> <span class="s2">&quot;/var/www/zoows-demo/map/data&quot;</span><span class="p">,</span>
441    <span class="nx">tmpPath</span><span class="o">:</span> <span class="s2">&quot;/var/www/temp&quot;</span><span class="p">,</span>
442    <span class="nx">tmpUrl</span><span class="o">:</span> <span class="s2">&quot;../temp&quot;</span><span class="p">,</span>
443    <span class="nx">cacheDir</span><span class="o">:</span> <span class="s2">&quot;/var/www/temp/&quot;</span>
444  <span class="p">},</span>
445  <span class="s2">&quot;identification&quot;</span><span class="o">:</span> <span class="p">{</span>
446    <span class="nx">title</span><span class="o">:</span> <span class="s2">&quot;The ZOO-Project WPS Server FOSS4G 2013 Nottingham Workshop&quot;</span><span class="p">,</span>
447    <span class="nx">keywords</span><span class="o">:</span> <span class="s2">&quot;WPS,GIS,buffer&quot;</span><span class="p">,</span>
448    <span class="kr">abstract</span><span class="o">:</span> <span class="s2">&quot;Demo version of Zoo-Project for OSGeoLiveDVD 2013. See http://www.zoo-project.org&quot;</span><span class="p">,</span>
449    <span class="nx">accessConstraints</span><span class="o">:</span> <span class="s2">&quot;none&quot;</span><span class="p">,</span>
450    <span class="nx">fees</span><span class="o">:</span> <span class="s2">&quot;None&quot;</span>
451  <span class="p">},</span>
452  <span class="s2">&quot;provider&quot;</span><span class="o">:</span> <span class="p">{</span>
453    <span class="nx">positionName</span><span class="o">:</span> <span class="s2">&quot;Developer&quot;</span><span class="p">,</span>
454    <span class="nx">providerName</span><span class="o">:</span> <span class="s2">&quot;ZOO-Project&quot;</span><span class="p">,</span>
455    <span class="nx">addressAdministrativeArea</span><span class="o">:</span> <span class="s2">&quot;Lattes&quot;</span><span class="p">,</span>
456    <span class="nx">addressCountry</span><span class="o">:</span> <span class="s2">&quot;fr&quot;</span><span class="p">,</span>
457    <span class="nx">phoneVoice</span><span class="o">:</span> <span class="s2">&quot;False&quot;</span><span class="p">,</span>
458    <span class="nx">addressPostalCode</span><span class="o">:</span> <span class="s2">&quot;34970&quot;</span><span class="p">,</span>
459    <span class="nx">role</span><span class="o">:</span> <span class="s2">&quot;Dev&quot;</span><span class="p">,</span>
460    <span class="nx">providerSite</span><span class="o">:</span> <span class="s2">&quot;http://www.zoo-project.org&quot;</span><span class="p">,</span>
461    <span class="nx">phoneFacsimile</span><span class="o">:</span> <span class="s2">&quot;False&quot;</span><span class="p">,</span>
462    <span class="nx">addressElectronicMailAddress</span><span class="o">:</span> <span class="s2">&quot;gerald.fenoy@geolabs.fr&quot;</span><span class="p">,</span>
463    <span class="nx">addressCity</span><span class="o">:</span> <span class="s2">&quot;Denver&quot;</span><span class="p">,</span>
464    <span class="nx">individualName</span><span class="o">:</span> <span class="s2">&quot;Gérald FENOY&quot;</span>
465  <span class="p">}</span>
466</pre></div>
467</td></tr></table></div>
468<p>In the following you get a sample outputs value passed to a Python or a JavaScript Service:</p>
469<div class="highlight-javascript"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
4702
4713
4724
4735
4746
4757</pre></div></td><td class="code"><div class="highlight"><pre><span class="p">{</span>
476  <span class="s1">&#39;Result&#39;</span><span class="o">:</span> <span class="p">{</span>
477    <span class="s1">&#39;mimeType&#39;</span><span class="o">:</span> <span class="s1">&#39;application/json&#39;</span><span class="p">,</span>
478    <span class="s1">&#39;inRequest&#39;</span><span class="o">:</span> <span class="s1">&#39;true&#39;</span><span class="p">,</span>
479    <span class="s1">&#39;encoding&#39;</span><span class="o">:</span> <span class="s1">&#39;UTF-8&#39;</span>
480  <span class="p">}</span>
481<span class="p">}</span>
482</pre></div>
483</td></tr></table></div>
484<div class="admonition note">
485<p class="first admonition-title">Note</p>
486<p class="last">the <code class="docutils literal"><span class="pre">inRequest</span></code> 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.</p>
487</div>
488<p>ZOO-Project provide a ZOO-API which was originally only available for
489JavaScript services, but thanks to the work of the ZOO-Project
490community, now you have also access to a ZOO-API when using
491the Python language. Thanks to the Python ZOO-API you don&#8217;t have to remember anymore
492the value of SERVICE_SUCCEDED and SERVICE_FAILED, you
493have the capability to translate any string from your Python service
494by calling the <code class="docutils literal"><span class="pre">_</span></code> function (ie: <code class="docutils literal"><span class="pre">zoo._('My</span> <span class="pre">string</span> <span class="pre">to</span>
495<span class="pre">translate')</span></code>) or to update the current status of a running service by
496using the <code class="docutils literal"><span class="pre">update_status</span></code> function the same way you use it from
497JavaScript or C services.</p>
498</div>
499<div class="section" id="the-hello-service">
500<h3><a class="toc-backref" href="#table-of-contents">The Hello Service</a><a class="headerlink" href="#the-hello-service" title="Permalink to this headline"></a></h3>
501<p>You can copy and paste the following into the
502<code class="docutils literal"><span class="pre">/home/user/zoo-ws2013/ws_sp/cgi-env/test_service.py</span></code> file.</p>
503<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">zoo</span>
504<span class="k">def</span> <span class="nf">Hello</span><span class="p">(</span><span class="n">conf</span><span class="p">,</span><span class="n">inputs</span><span class="p">,</span><span class="n">outputs</span><span class="p">):</span>
505    <span class="n">outputs</span><span class="p">[</span><span class="s">&quot;Result&quot;</span><span class="p">][</span><span class="s">&quot;value&quot;</span><span class="p">]</span><span class="o">=</span>\
506            <span class="s">&quot;Hello &quot;</span><span class="o">+</span><span class="n">inputs</span><span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">][</span><span class="s">&quot;value&quot;</span><span class="p">]</span><span class="o">+</span><span class="s">&quot; from the ZOO-Project Python world !&quot;</span>
507    <span class="k">return</span> <span class="n">zoo</span><span class="o">.</span><span class="n">SERVICE_SUCCEEDED</span>
508</pre></div>
509</div>
510<p>Once you finish editing the file, you should copy it in the <code class="docutils literal"><span class="pre">/usr/lib/cgi-bin</span></code> directory:</p>
511<div class="highlight-none"><div class="highlight"><pre>sudo cp /home/user/zoo-ws2013/ws_sp/cgi-env/* /usr/lib/cgi-bin
512</pre></div>
513</div>
514</div>
515</div>
516<div class="section" id="interracting-with-your-service-using-execute-requests">
517<h2><a class="toc-backref" href="#table-of-contents">Interracting with your service using Execute requests</a><a class="headerlink" href="#interracting-with-your-service-using-execute-requests" title="Permalink to this headline"></a></h2>
518<p>Now, you can request for Execute using the following basic url:</p>
519<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto
520</pre></div>
521</div>
522<p>You can request the WPS Server to return a XML WPS Response containing the result of
523your computation, requesting for ResponseDocument or you can access the data directly
524requesting for RawDataOutput.</p>
525<ul class="simple">
526<li>Sample request using the RawDataOutput parameter:</li>
527</ul>
528<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;RawDataOutput=Result
529</pre></div>
530</div>
531<ul class="simple">
532<li>Sample request using the default ResponseDocument parameter:</li>
533</ul>
534<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;ResponseDocument=Result
535</pre></div>
536</div>
537<p>When you are using ResponseDocument there is specific attribut you can use to ask
538the ZOO Kernel to store the result: <code class="docutils literal"><span class="pre">asReference</span></code>. You can use the following example:</p>
539<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;ResponseDocument=Result@asReference=true
540</pre></div>
541</div>
542<p>When computation take long time, the client should request the
543execution of a Service by setting both <code class="docutils literal"><span class="pre">storeExecuteResponse</span></code> and
544<code class="docutils literal"><span class="pre">status</span></code> parameter to true to force asynchronous execution. This
545will make the ZOO-Kernel return, without waiting for the Service execution
546completion but after starting another ZOO-Kernel process responsible
547of the Service execution, a ResponseDocument containing a <code class="docutils literal"><span class="pre">statusLocation</span></code>
548attribute which can be used to access the status of an ongoing service
549or the result when the process ended <a class="footnote-reference" href="#f3" id="id3">[3]</a>.</p>
550<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;ResponseDocument=Result&amp;storeExecuteResponse=true&amp;status=true
551</pre></div>
552</div>
553</div>
554<div class="section" id="conclusion">
555<h2><a class="toc-backref" href="#table-of-contents">Conclusion</a><a class="headerlink" href="#conclusion" title="Permalink to this headline"></a></h2>
556<p>Even if this first service was really simple it was useful to illustrate how the
557ZOO-Kernel fill <code class="docutils literal"><span class="pre">conf</span></code>, <code class="docutils literal"><span class="pre">inputs</span></code> and <code class="docutils literal"><span class="pre">outputs</span></code> parameter prior to load
558and run your function service, how to write a ZCFG file, how to publish a Services
559Provider by placing the ZCFG and Python files in the same directory as the
560ZOO-Kernel, then how to interract with your service using both
561<code class="docutils literal"><span class="pre">GetCapabilities</span></code>, <code class="docutils literal"><span class="pre">DescribeProcess</span></code> and <code class="docutils literal"><span class="pre">Execute</span></code> requesr. We will see
562in the <a class="reference external" href="building_blocks_presentation.html">next section</a> how to write similar requests
563using the XML syntax.</p>
564<p class="rubric">Footnotes</p>
565<table class="docutils footnote" frame="void" id="f1" rules="none">
566<colgroup><col class="label" /><col /></colgroup>
567<tbody valign="top">
568<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><code class="docutils literal"><span class="pre">SERVICE_FAILED=4</span></code></td></tr>
569</tbody>
570</table>
571<table class="docutils footnote" frame="void" id="f2" rules="none">
572<colgroup><col class="label" /><col /></colgroup>
573<tbody valign="top">
574<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td><code class="docutils literal"><span class="pre">SERVICE_SUCCEEDED=3</span></code></td></tr>
575</tbody>
576</table>
577<table class="docutils footnote" frame="void" id="f3" rules="none">
578<colgroup><col class="label" /><col /></colgroup>
579<tbody valign="top">
580<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>To get on-going status url in <code class="docutils literal"><span class="pre">statusLocation</span></code>, you&#8217;ll need to setup the <a class="reference external" href="http://www.zoo-project.org/trac/browser/trunk/zoo-project/zoo-services/utils/status">utils/status</a> Service. If you don&#8217;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.</td></tr>
581</tbody>
582</table>
583</div>
584</div>
585
586
587          </div>
588          <footer>
589 
590    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
591     
592        <a href="building_blocks_presentation.html" class="btn btn-neutral float-right" title="Building blocks presentation - Using OGR and PgRouting based Web Services">Next <span class="fa fa-arrow-circle-right"></span></a>
593     
594     
595        <a href="using_zoo_from_osgeolivevm.html" class="btn btn-neutral" title="Configuration and ZOO-Kernel use"><span class="fa fa-arrow-circle-left"></span> Previous</a>
596     
597    </div>
598 
599
600  <hr/>
601  <div class="pfoot">
602  <div role="contentinfo">
603    <p>
604        &copy; Copyright 2009-2015, ZOO-Project team.
605    </p>
606  </div>
607  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> inspired by <a href="https://readthedocs.org">Read the Docs</a>.
608</div>
609</footer>
610
611        </div>
612      </div>
613
614    </section>
615
616  </div>
617 
618
619
620 
621
622    <script type="text/javascript">
623        var DOCUMENTATION_OPTIONS = {
624            URL_ROOT:'./',
625            VERSION:'1.5',
626            COLLAPSE_INDEX:false,
627            FILE_SUFFIX:'.html',
628            HAS_SOURCE:  true
629        };
630    </script>
631      <script type="text/javascript" src="_static/jquery.js"></script>
632      <script type="text/javascript" src="_static/underscore.js"></script>
633      <script type="text/javascript" src="_static/doctools.js"></script>
634
635 
636
637 
638 
639    <script type="text/javascript" src="_static/js/theme.js"></script>
640 
641
642 
643 
644  <script type="text/javascript">
645      jQuery(function () {
646          SphinxRtdTheme.StickyNav.enable();
647      });
648  </script>
649   
650
651</body>
652</html>
Note: See TracBrowser for help on using the repository browser.

Download now !

Search

Context Navigation

Main Navigation

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