Configuring and Using Web Services
Introduction
Hydstra provides tools to enable access to Hydstra data via
SOAP and REST web services.
The REST web service uses the GET method by default (via a standard URL request).
The web service also supports POST requests.
To configure Hydstra web services you will need the following:
• A Hydstra/WSI (or WEB) licence in your HYACCESS.INI file
• A user in PASSWD with a WSI or WEB licence (any level)
• The service must run using a Hydstra user with a WSI or WEB licence
Through the implementation of custom code (to initiate a data request and process the data response) you have direct access to the data you may require for data modelling, data reports or new web based data presentation.
Custom code for SOAP may be developed on any software platform that supports SOAP.
A template Perl script is provided as a web service gateway to data access methods provided via the Hydstra DLL (HYDLLP) in the host Hydstra system.
The template Hydstra Perl web service is supplied in the ..\web\wsys\cgi folder and its URL will be something like http://127.0.0.1/cgi/webservice.pl
The related WSDL (Web services Description Language) file URL will be http://127.0.0.1/wini/webservice.wsdl
Configuring the web server environment
It is assumed that you have synchronised your Hydstra system to your web server using Syncovery or a similar tool.
Further, you have already added all the required web userclass records to CODES:PWWEBUC via the SYSADMIN Manage and added and configured the required users to PASSWD.
In addition you have already added the global environment variables PERL5LIB (equal to your Hydstra RUNPATH) and added RUNPATH and the Perl BIN path to the PATH environment variable.
You have also installed IIS, created a web site whose root is WEBPATH ( ..\hyd\web), added a script mapping for Perl and given the IUSR account Full Control permissions to the whole Hydstra folder structure.
You must now create a virtual directory 'wsi' for the WINIPATH WSI folder (..\hyd\web\wini\wsi\).
Configurable web services
By default the web service will retrieve data from the host Hydstra system according to its HYCONFIG environment. If you wish to establish a web service called from your domain that accesses data in an alternative Hydstra dataset, you may clone the template web service Perl script and direct it to use a different HYCONFIG environment as follows.
Copy ..\hyd\web\wsys\cgi\webservice.pl to a labelled sub
folder of the WINIPATH WSI folder (e.g. ..\hyd\web\wini\wsi\dwr\webservice.pl).
Create the folders if they do not already exist.
Open the file with a flat text editor (we recommend
Notepad++) and set the variable $CONFPATH to the full path and filename
of a HYCONFIG ini file that establishes your desired web service environment. Do
NOT edit any other code in the Perl script.
For example:
my $CONFPATH = 'C:/Hydstra/webv10/hyd/hyconfigws.ini';
NOTE: the HYCONFIG ini file may have any name (not
just HYCONFIG.INI) and can be located in any accessible folder so long as
the matching HYACCESS file is present in the same folder. (Forward slashes in the CONFPATH setting are
acceptable.)
The HYCONFIG file must contain appropriate [Path Prefixes] settings.
It is recommended that you should make the \TEMP\ setting the same as that of
your host Hydstra system so that your scheduled WEBCLEAN task will be able to
remove stale temporary folders and files.
Here are some example HYCONFIG files for different
scenarios:
1. a different system (and its standard DAT path):
[Version]
Version = 1
[Path Prefixes]
\HYD\=C:\hydstra\v10
\TEMP\=C:\hydstra\prod
2. the host system and a non-standard DAT path:
[Version]
Version = 1
[Path Prefixes]
\HYD\=C:\hydstra\prod
\HYD\DAT\=C:\hydstra\project
\TEMP\=C:\hydstra\prod
3. a different system and a non-standard DAT path:
[Version]
Version = 1
[Path Prefixes]
\HYD\=C:\hydstra\v10
\HYD\DAT\=C:\hydstra\v10\proj
\TEMP\=C:\hydstra\prod
You will also need to clone and amend the WSDL file from ..\hyd\web\wini\ to match your requirements.
The REST URL for your configured web service will be something like
http://127.0.0.1/wsi/dwr/webservice.pl?{"function":"get_variable_list","version":1,"params":{"site_list":"gw000002","datasource":"CP"}}
Please contact KISTERS if you require assistance with web services scripting.
Web service queueing
To manage server load due to excessive web service calls,
jobs are automatically queued using Perl. Three environment variables may be
set to override defaults for maximum concurrent jobs, maximum age of jobs and
the port used for job queue management communications. Each environment
variable may be set in the configurable script (e.g. in the WSI folder) in Perl
using the $ENV{setting} syntax, or in Control Panel -> System -> Advanced
-> Environment Variables…
IMPORTANT: You must reboot the webserver
after setting these system level environment variables.
MAXWSTHREADS – the maximum number of concurrent web
service threads.
This limits the number of concurrent DLL calls by the web service processes
– default 2
WSJOBMAXAGE – the maximum age of web service jobs (in
seconds).
This limits the length of time a web service DLL call job will wait in the
queue before quitting – default 300
WSSOCKETPORT – the port used for socket inter process communication to manage web service queueing – default 7890
WSMAXQLENGTH – maximum number of DLL jobs that may be added to the queue – default 20
REST Request and Response with JSON
The data request is made by passing a JSON structure appended as a URL query. For example:
The details of the request JSON structure will depend upon which DLL JSONCall function you choose. The example uses the get_ts_traces DLL function. Please see the HYDLLP documentation for the latest available function names and parameters.
The response to the previous request may look something like this:
{"buff_required": 613, "buff_supplied": 50000, "error_num": 0, "_return": {"traces": [{"trace": [{"q": 130, "v": "0.367", "t": 19750801000000}, {"q": 130, "v": "0.365", "t": 19750802000000}], "site": "201001", "varfrom_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}, "site_details": {"short_name": "OXLEY @ EUNGELLA", "name": "OXLEY RIVER AT EUNGELLA"}, "compressed": "0", "quality_codes": {"zzzzzz_130": "Not quality coded - subject to change"}, "varto_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}}]}}
The REST web service may also be used for Hydstra systems
with multiple DAT paths. The web portal must be correctly configured with a set
of web userclasses with matching login credentials in the PASSWD table (the
users' PASSWD:WEBUSERCLS fields must be populated). In addition there must
exist a HYCONFIG template file for the userclass residing in WGENPATH
(..\hyd\web\wgen) called hyconfig.[userclass].ini. For example:
..\hyd\web\wgen\hyconfig.admin.ini
The template file may be generated by the main portal WEBBUILDER process or you
must create it yourself.
To enable the web service to access the correct data you must supply the username and password of the required userclass user as part of the web service URL.
http://mydomain.com/cgi/webservice.pl?{"function":"get_db_info","version":"3","params":{"table_name":"site","return_type":"array"}}&user=myname&pass=mypassword
The REST web service may also optionally generate a naked JSON data structure by passing the parameter naked=1. The response would look like:
{"traces": [{"trace": [{"q": 130, "v": "0.367", "t": 19750801000000}, {"q": 130, "v": "0.365", "t": 19750802000000}], "site": "201001", "varfrom_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}, "site_details": {"short_name": "OXLEY @ EUNGELLA", "name": "OXLEY RIVER AT EUNGELLA"}, "compressed": "0", "quality_codes": {"zzzzzz_130": "Not quality coded - subject to change"}, "varto_details": {"subdesc": "", "variable": "100.00", "short_name": "Level (Metres)", "name": "Stream Water Level", "units": "Metres"}}]}
The REST web service response structures contain special key
modifications (pre-appending ‘_’ to the return key and
pre-appending zzzzzz_ to all keys starting with a digit. (These modifications
were added to support fussy behaviour in browser Javascript code which is now
not essential due to better browser standards compliance and new JSON parsing
techniques.)
This behaviour is the default but you may omit these modifications if you
specify the parameter ver=2. For example:
http://127.0.0.1/cgi/webservice.pl?{"function":"get_latest_ts_values","version":"2","params":{"site_list":"201001","datasource":"A","trace_list":[{"varfrom":"100.00","varto":"100.00"}]}}&ver=2
will return:
{"buff_required": 220, "buff_supplied": 50000, "error_num": 0, "return": {"201001": [{"varfrom": "100.00", "values": [{"time_start": "", "p": "", "time_end": "", "time": "20150728133000", "q": 3, "v": "0.434", "trend": "-"}], "varto": "100.00"}]}}
instead of:
{"buff_required": 220, "buff_supplied": 50000, "error_num": 0, "_return": {"zzzzzz_201001": [{"varfrom": "100.00", "values": [{"time_start": "", "p": "", "time_end": "", "time": "20150728133000", "q": 3, "v": "0.434", "trend": "-"}], "varto": "100.00"}]}}
Normally the web service supplies the content type header text/html for use in web browsers. To specify an alternative, you must append the mime parameter. The options are html and csv. For example:
http://127.0.0.1/cgi/webservice.pl?{"function":"get_latest_ts_values","version":"2","params":{"site_list":"201001","datasource":"A","trace_list":[{"varfrom":"100.00","varto":"100.00"}]}}&ver=2&mime=csv
which will return the MIME header text/csv.
REST requests with conventional parameter pairs
As an alternative to the JSON request format, you may use
conventional parameter pairs on some calls.
This approach is currently only available for get_ts_traces, get_latest_ts_values,
get_db_info but may be extended to support other calls in the future.
For example:
http://127.0.0.1/cgi/webservice.pl?function=get_ts_traces&site_list=HYDSYS01,HYDSYS02&datasource=A&varfrom=100.00&varto=100.00&start_time=19750801000000&end_time=19750802000000&data_type=mean&interval=day&multiplier=1
http://127.0.0.1/cgi/webservice.pl?function=get_latest_ts_values&site_list=hydsys01&datasource=A&varfrom=100.00&varto=100&lookback=60
http://127.0.0.1/cgi/webservice.pl?function=get_db_info&field_list=bdate,bench,elev,rlgd,method&table_name=bench&sitelist_filter=201001
REST response in CSV format
As an alternative to the JSON response format, you may request
CSV format (for JSON and parameter pair requests) using the parameter format=csv.
This approach is currently only available for get_ts_traces, get_latest_ts_values,
get_db_info but may be extended to support other calls in the future.
For example:
http://127.0.0.1/cgi/webservice.pl?{"function":"get_db_info","version":3,"params":{"table_name":"site","field_list":["station","stname"],"return_limit":10,"return_type":"array"}}&format=csv
returns:
station,stname
0,Dummy Site for Hydstra Purposes
012001,HOMESTEAD CREEK AT FOWLERS GAP
012002,FRIESLICH CREEK AT FRIESLICH DAM
012003,FOWLERS CREEK AT FOWLERS GAP
040000,ABBOTSFORD (CBM)
040001,ACACIA VALE (CBM)
040002,AMAMOOR (CBM)
040003,AMAMOUR EAST (CBM)
040004,AMBERLEY AMO (CBM)
040005,ANDERLEIGH (CBM)
http://127.0.0.1/cgi/webservice.pl?function=get_latest_ts_values&site_list=hydsys01&datasource=A&varfrom=100.00&varto=100&lookback=60&format=csv
returns:
site,var,time,value,quality,trend
HYDSYS01,100.00,19870226101500,0.049,1,0
If you use the alternative parameter format=csvc, a trailing comma will be appended to the end of every line. For example:
site,var,time,value,quality,trend,
HYDSYS01,100.00,19870226101500,0.049,1,0,
Sample VBA Excel REST code
Sample provided at ..\HYD\SYS\perl\examples\webservice.bas
Option Explicit
Sub http()
Dim url As String
Dim MyRequest As Object
Set MyRequest = CreateObject("WinHttp.WinHttpRequest.5.1")
' MyRequest.Open "GET",
"http://203.12.195.133/cgi/webservice.pl?wsver"
url = "http://203.12.195.133/cgi/webservice.pl?{""function"":""get_db_info"",""version"":""3"",""params"":{""table_name"":""site"",""return_type"":""hash"",""filter_values"":{""station"":""221001""}}}&ver=2"
'url =
"http://data.water.vic.gov.au/cgi/webservice.pl?{""function"":""get_db_info"",""version"":""3"",""params"":{""table_name"":""site"",""return_type"":""hash"",""filter_values"":{""station"":""221001""}}}&ver=2"
' MsgBox url
MyRequest.Open "GET", url
MyRequest.send
MsgBox MyRequest.responseText
End Sub
POST requests
To avoid the URL length limit, you may make web service requests with the POST method.
SOAP Request and Response
The data request is a block of XML which includes a JSON data structure specifying:
• a Hydstra DLL function name
• the function's parameter names and values
• the version number of the DLL data request protocol
plus the buffer size for the data response (in bytes).
Please see the HYDLLP documentation for the latest available function names and parameters.
For example, use the following to request the mean daily stream level archive data for sites HYDSYS01 and HYDSYS02 from 1/8/1975 to 1/9/1975:
<?xml version="1.0"
encoding="UTF-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<JSonCall xmlns="http://203.3.195.115/WebService">
<c-gensym5 xsi:type="xsd:string">
{"params":
{"site_list": "HYDSYS01,HYDSYS02",
"start_time": "19750801000000",
"varfrom": "100.00",
"interval": "day",
"varto": "100.00",
"datasource": "A",
"end_time": "19750901000000",
"data_type": "mean",
"multiplier": "1"},
"function": "get_ts_traces",
"version": 1}
}
</c-gensym5>
<c-gensym7 xsi:type="xsd:int">
1000000
</c-gensym7>
</JSonCall>
</soap:Body>
</soap:Envelope>
The data response is a block of XML containing a JSON data structure including:
• a process error code (and message if necessary)
• the size of the response (bytes)
• various relevant meta data plus the requested data types and values
• the size of the supplied buffer size (bytes)
The corresponding response XML is:
<?xml version="1.0"
encoding="UTF-8"?>
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<JSonCallResponse xmlns="http://203.3.195.115/WebService">
<s-gensym3 xsi:type="xsd:string">
{"error_num":0,
"buff_required":"3477",
"return":{
"traces":[{
"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Composite
data"},
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.363","t":19750801000000,"q":1},
{"v":"0.368","t":19750802000000,"q":1},
{"v":"0.363","t":19750803000000,"q":1},
{"v":"0.464","t":19750804000000,"q":1},
{"v":"0.505","t":19750805000000,"q":1},
{"v":"0.417","t":19750806000000,"q":1},
{"v":"0.368","t":19750807000000,"q":1},
{"v":"0.318","t":19750808000000,"q":1},
{"v":"0.294","t":19750809000000,"q":1},
{"v":"0.285","t":19750810000000,"q":1},
{"v":"0.308","t":19750811000000,"q":1},
{"v":"0.461","t":19750812000000,"q":1},
{"v":"0.507","t":19750813000000,"q":1},
{"v":"0.457","t":19750814000000,"q":1},
{"v":"0.396","t":19750815000000,"q":1},
{"v":"0.369","t":19750816000000,"q":1},
{"v":"0.354","t":19750817000000,"q":1},
{"v":"0.344","t":19750818000000,"q":1},
{"v":"0.328","t":19750819000000,"q":1},
{"v":"0.275","t":19750820000000,"q":1},
{"v":"0.251","t":19750821000000,"q":1},
{"v":"0.243","t":19750822000000,"q":1},
{"v":"0.237","t":19750823000000,"q":1},
{"v":"0.228","t":19750824000000,"q":1},
{"v":"0.222","t":19750825000000,"q":1},
{"v":"0.221","t":19750826000000,"q":1},
{"v":"0.267","t":19750827000000,"q":1},
{"v":"0.349","t":19750828000000,"q":1},
{"v":"0.300","t":19750829000000,"q":1},
{"v":"0.254","t":19750830000000,"q":1},
{"v":"0.231","t":19750831000000,"q":1},
{"v":"0.220","t":19750901000000,"q":1}],
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres","name":"Stream Water
Level"},
"site":"HYDSYS01",
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"}
},
{"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Secondary rainfall
data" },
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.363","t":19750801000000,"q":1},
{"v":"0.368","t":19750802000000,"q":1},
{"v":"0.363","t":19750803000000,"q":1},
{"v":"0.464","t":19750804000000,"q":1},
{"v":"0.505","t":19750805000000,"q":1},
{"v":"0.417","t":19750806000000,"q":1},
{"v":"0.368","t":19750807000000,"q":1},
{"v":"0.318","t":19750808000000,"q":1},
{"v":"0.294","t":19750809000000,"q":1},
{"v":"0.285","t":19750810000000,"q":1},
{"v":"0.308","t":19750811000000,"q":1},
{"v":"0.461","t":19750812000000,"q":1},
{"v":"0.507","t":19750813000000,"q":1},
{"v":"0.457","t":19750814000000,"q":1},
{"v":"0.396","t":19750815000000,"q":1},
{"v":"0.369","t":19750816000000,"q":1},
{"v":"0.354","t":19750817000000,"q":1},
{"v":"0.344","t":19750818000000,"q":1},
{"v":"0.328","t":19750819000000,"q":1},
{"v":"0.275","t":19750820000000,"q":1},
{"v":"0.251","t":19750821000000,"q":1},
{"v":"0.243","t":19750822000000,"q":1},
{"v":"0.237","t":19750823000000,"q":1},
{"v":"0.228","t":19750824000000,"q":1},
{"v":"0.222","t":19750825000000,"q":1},
{"v":"0.221","t":19750826000000,"q":1},
{"v":"0.267","t":19750827000000,"q":1},
{"v":"0.349","t":19750828000000,"q":1},
{"v":"0.300","t":19750829000000,"q":1},
{"v":"0.254","t":19750830000000,"q":1},
{"v":"0.231","t":19750831000000,"q":1},
{"v":"0.220","t":19750901000000,"q":1}],
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"site":"HYDSYS02",
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"}
}
]
},
"buff_supplied":8192}
</s-gensym3>
</JSonCallResponse>
</soap:Body>
</soap:Envelope>
The SOAP web service may also be used for Hydstra systems with multiple DAT paths. The web portal must be correctly configured with a set of web userclasses with matching login credentials in the PASSWD table (the users' PASSWD:WEBUSERCLS fields must be populated).
To enable the web service to access the correct data, you must supply the username and password of the required userclass user as part of the SOAP request. There are several ways to do this in Perl (see ..\HYD\SYS\perl\examples\webservice.client.pl):
my $buffersize = 1000000;
my %parameters = (
'function' => 'get_ts_traces',
'version' => 2,
'params' => {
'site_list' => $siteid,
'datasource' => 'A',
'varfrom' => '100.00',
'varto' => '100.00',
'start_time' => $start,
'end_time' => $end,
'data_type' => 'mean',
'interval' => 'day',
'multiplier' => '1'
},
'user' => $username,
'pass' => $password,
);
Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy
request Perl reference)\n", HashDump(\%parameters), "\n");
my $json = SOAP::Lite
-> uri($uri)
-> proxy($proxy, options => {compress_threshold =>
10000})
-> JSonCall(\%parameters,$buffersize)
-> result;
Prt('-S', "returned JSON:\n", $json);
# -----------------------------------------------------
my $request_string = qq[{"function":"get_ts_traces",
"version":2,
"params":{
"site_list":"$siteid",
"datasource":"A",
"varfrom":"100.00",
"varto":"100.00",
"start_time":"$start",
"end_time":"$end",
"data_type":"mean",
"interval":"day",
"multiplier":"1"
},
"user":"$username",
"pass":"$password",
}];
Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy
request string)\n$request_string\n");
$json = SOAP::Lite
-> uri($uri)
-> proxy($proxy, options => {compress_threshold => 10000})
-> JSonCall($request_string,$buffersize)
-> result;
Prt('-S', "returned JSON:\n", $json);
The REST web service may also optionally generate a naked JSON data structure by passing the parameter naked=1. The response would look like:
<?xml version="1.0"
encoding="UTF-8"?>
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<JSonCallResponse xmlns="http://203.3.195.115/WebService">
<s-gensym3 xsi:type="xsd:string">
{
"traces":[{
"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Composite
data"},
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.363","t":19750801000000,"q":1},
{"v":"0.368","t":19750802000000,"q":1},
{"v":"0.363","t":19750803000000,"q":1},
{"v":"0.464","t":19750804000000,"q":1},
{"v":"0.505","t":19750805000000,"q":1},
{"v":"0.417","t":19750806000000,"q":1},
{"v":"0.368","t":19750807000000,"q":1},
{"v":"0.318","t":19750808000000,"q":1},
{"v":"0.294","t":19750809000000,"q":1},
{"v":"0.285","t":19750810000000,"q":1},
{"v":"0.308","t":19750811000000,"q":1},
{"v":"0.461","t":19750812000000,"q":1},
{"v":"0.507","t":19750813000000,"q":1},
{"v":"0.457","t":19750814000000,"q":1},
{"v":"0.396","t":19750815000000,"q":1},
{"v":"0.369","t":19750816000000,"q":1},
{"v":"0.354","t":19750817000000,"q":1},
{"v":"0.344","t":19750818000000,"q":1},
{"v":"0.328","t":19750819000000,"q":1},
{"v":"0.275","t":19750820000000,"q":1},
{"v":"0.251","t":19750821000000,"q":1},
{"v":"0.243","t":19750822000000,"q":1},
{"v":"0.237","t":19750823000000,"q":1},
{"v":"0.228","t":19750824000000,"q":1},
{"v":"0.222","t":19750825000000,"q":1},
{"v":"0.221","t":19750826000000,"q":1},
{"v":"0.267","t":19750827000000,"q":1},
{"v":"0.349","t":19750828000000,"q":1},
{"v":"0.300","t":19750829000000,"q":1},
{"v":"0.254","t":19750830000000,"q":1},
{"v":"0.231","t":19750831000000,"q":1},
{"v":"0.220","t":19750901000000,"q":1}],
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres","name":"Stream Water
Level"},
"site":"HYDSYS01",
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"}
},
{"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Secondary rainfall
data" },
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.363","t":19750801000000,"q":1},
{"v":"0.368","t":19750802000000,"q":1},
{"v":"0.363","t":19750803000000,"q":1},
{"v":"0.464","t":19750804000000,"q":1},
{"v":"0.505","t":19750805000000,"q":1},
{"v":"0.417","t":19750806000000,"q":1},
{"v":"0.368","t":19750807000000,"q":1},
{"v":"0.318","t":19750808000000,"q":1},
{"v":"0.294","t":19750809000000,"q":1},
{"v":"0.285","t":19750810000000,"q":1},
{"v":"0.308","t":19750811000000,"q":1},
{"v":"0.461","t":19750812000000,"q":1},
{"v":"0.507","t":19750813000000,"q":1},
{"v":"0.457","t":19750814000000,"q":1},
{"v":"0.396","t":19750815000000,"q":1},
{"v":"0.369","t":19750816000000,"q":1},
{"v":"0.354","t":19750817000000,"q":1},
{"v":"0.344","t":19750818000000,"q":1},
{"v":"0.328","t":19750819000000,"q":1},
{"v":"0.275","t":19750820000000,"q":1},
{"v":"0.251","t":19750821000000,"q":1},
{"v":"0.243","t":19750822000000,"q":1},
{"v":"0.237","t":19750823000000,"q":1},
{"v":"0.228","t":19750824000000,"q":1},
{"v":"0.222","t":19750825000000,"q":1},
{"v":"0.221","t":19750826000000,"q":1},
{"v":"0.267","t":19750827000000,"q":1},
{"v":"0.349","t":19750828000000,"q":1},
{"v":"0.300","t":19750829000000,"q":1},
{"v":"0.254","t":19750830000000,"q":1},
{"v":"0.231","t":19750831000000,"q":1},
{"v":"0.220","t":19750901000000,"q":1}],
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"site":"HYDSYS02",
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"}
}
]
}
</s-gensym3>
</JSonCallResponse>
</soap:Body>
</soap:Envelope>
Sample Perl code for SOAP
A sample Perl script is provided to exercise several variants of SOAP requests at ..\HYD\SYS\perl\examples\webservice.client.pl
use strict;
use Compress::Zlib;
use SOAP::Lite;
#use SOAP::Lite 'trace', 'debug';
use JSON;
use CGI;
require 'hydlib.pl';
sub urldecode {
my $s = shift;
$s =~ s/\%([A-Fa-f0-9]{2})/pack('C', hex($1))/seg;
$s =~ s/\+/ /g;
return $s;
}
main: {
system('cls');
my $domain = 'realtimedata.water.nsw.gov.au';
my $uri = "http://$domain/WebService";
my $proxy = "http://$domain/cgi/webservice.pl";
my $service = "http://$domain/wini/webservice.wsdl";
my $query = new CGI;
print $query->header(-Accept_encoding => 'deflate');
Prt('-S', NowStr(), " Started $0\n");
Prt('-S', "domain: $domain\nuri: $uri\nproxy: $proxy\nservice:
$service\n\n");
# -----------------------------------------------------
Prt('-S', NowStr(), " - running helloWorld (proxy)\n");
my $return_string = SOAP::Lite
-> uri($uri)
-> proxy($proxy, options => {compress_threshold
=> 10000})
-> helloWorld
-> result;
Prt('-S', "helloWorld returned [$return_string]\n\n");
# -----------------------------------------------------
Prt('-S', NowStr(), " - running helloWorld (wsdl)\n");
$return_string = SOAP::Lite
-> service($service)
-> helloWorld;
Prt('-S', "helloWorld returned [$return_string]\n");
# -----------------------------------------------------
my $buffersize = 1000000;
my %parameters = (
'function' => 'get_ts_traces',
'version' => 2,
'params' => {
'site_list' => '201001',
'datasource' => 'A',
'varfrom' => '100.00',
'varto' => '100.00',
'start_time' => '19750501000000',
'end_time' => '19750510000000',
'data_type' => 'mean',
'interval' => 'day',
'multiplier' => '1'
}
);
Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy
request Perl reference)\n", HashDump(\%parameters), "\n");
my $json = SOAP::Lite
-> uri($uri)
-> proxy($proxy, options => {compress_threshold =>
10000})
-> JSonCall(\%parameters,$buffersize)
-> result;
Prt('-S', "returned JSON:\n", $json);
# -----------------------------------------------------
my $request_string = qq[{"function":"get_ts_traces",
"version":2,
"params":{
"site_list":"201001",
"datasource":"A",
"varfrom":"100.00",
"varto":"100.00",
"start_time":"19750501000000",
"end_time":"19750510000000",
"data_type":"mean",
"interval":"day",
"multiplier":"1"
}
}];
Prt('-S', "\n\n", NowStr(), " - running JSonCall (proxy
request string)\n$request_string\n");
$json = SOAP::Lite
-> uri($uri)
-> proxy($proxy, options => {compress_threshold => 10000})
-> JSonCall($request_string,$buffersize)
-> result;
Prt('-S', "returned JSON:\n", $json);
# -----------------------------------------------------
Prt('-S', "\n\n", NowStr(), " - running JSonCall (wsdl
request string)\n$request_string\n");
$json = SOAP::Lite
-> service($service)
-> JSonCall($request_string,$buffersize);
Prt('-S', "returned JSON:\n", $json);
# -----------------------------------------------------
$request_string =
qq[%7B%22function%22%3A%22get_ts_traces%22%2C%22version%22%3A2%2C%22params%22%3A%7B%22site_list%22%3A%22201001%22%2C%22datasource%22%3A%22A%22%2C%22varfrom%22%3A%22100.00%22%2C%22varto%22%3A%22100.00%22%2C%22start_time%22%3A%2219750501000000%22%2C%22end_time%22%3A%2219750510000000%22%2C%22data_type%22%3A%22mean%22%2C%22interval%22%3A%22day%22%2C%22multiplier%22%3A%221%22%7D%7D];
Prt('-S', "\n\n", NowStr(), " - running JSonCall (wsdl
encoded request string)\n$request_string\n");
$json = SOAP::Lite
-> service($service)
-> JSonCall($request_string,$buffersize);
Prt('-S', "returned JSON:\n", $json);
Prt('-S', "\n\n", NowStr(), " end\n\n");
}
Sample WSDL (Webservices Description Language) file
Sample provided at \HYD\SYS\WDEF\wini\webservice.wsdl
Usually all you will need to amend are the URL domains at installation.
<?xml version="1.0"
encoding="UTF-8"?>
<definitions name="HydstraWebService"
targetNamespace="http://127.0.0.1/WebService"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://127.0.0.1/WebService"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<documentation>
This web service enables SOAP data requests from the Hydstra water database
of the [enter your organisation name here].
</documentation>
<message name="helloWorldRequest"/>
<message name="helloWorldResponse">
<part name="response" type="xsd:string"/>
</message>
<message name="JSonCallRequest">
<part name="call" type="xsd:string"/>
</message>
<message name="JSonCallResponse">
<part name="response" type="xsd:string"/>
</message>
<portType name="PortType">
<operation name="helloWorld">
<input message="tns:helloWorldRequest"/>
<output message="tns:helloWorldResponse"/>
</operation>
<operation name="JSonCall">
<input message="tns:JSonCallRequest"/>
<output message="tns:JSonCallResponse"/>
</operation>
</portType>
<binding name="Hydstra_Binding"
type="tns:PortType">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="helloWorld" namespace="http://127.0.0.1/WebService">
<soap:operation
soapAction="http://127.0.0.1/WebService#helloWorld"/>
<input>
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://127.0.0.1/WebService"
use="encoded"/>
</input>
<output>
<soap:body namespace="http://127.0.0.1/WebService"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
use="encoded"/>
</output>
</operation>
<operation name="JSonCall"
namespace="http://127.0.0.1/WebService">
<soap:operation
soapAction="http://127.0.0.1/WebService#JSonCall"/>
<input>
<soap:body namespace="http://127.0.0.1/WebService"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
use="encoded"/>
</input>
<output>
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://127.0.0.1/WebService"
use="encoded"/>
</output>
</operation>
</binding>
<service name="HydstraWebService">
<documentation>
This web service enables SOAP data requests from the Hydstra water
database of the [enter your organisation name here].
</documentation>
<port binding="tns:Hydstra_Binding"
name="Hydstra_Port">
<soap:address
location="http://127.0.0.1/cgi/webservice.pl"/>
</port>
</service>
</definitions>
See Also