If you are NOT using the ECMWF Gateways (ecaccess or msaccess) then please refer to the previous user guide for accessing the ECaccess Web Services V1. This documentation is about ECaccess Web Services V2 which is currently only available at ECMWF. At heart, ECaccess Web Services APIs use JSON as a data format and HTTPS as a protocol for data transmission. ECMWF has released a full-featured Perl client library to make interacting with ECaccess Web Services APIs easier. However, if Perl is not available on your platform or you are not able to install additional software then CURL is an alternative to interact with the ECaccess Web Services. CURL is a command-line application for performing requests using a variety of protocols including HTTPS, required to interact with the APIs at a low level. In this document we assume that you are already familiar with the ECaccess Services. If this is not the case then please have refer to other sections in this User Guide to learn about the concepts behind Gateways, Operations, Associations, Protocols, Files, Jobs, Events, Queues and Transfers.
...
Table of Contents | ||
---|---|---|
|
Obtaining CURL
CURL is commonly available on a default install of many UNIX/Linux platforms. Try typing curl in your favorite shell to see if it is installed and in your PATH. If you don't have the tool installed, visit the download page on the CURL website to obtain the official source or a user-contributed binary package: http://curl.haxx.se/download.html
Note that the command-line tool uses the libcurl library, which may be offered as a separate download package, so, if you're not compiling from the source, be sure to download a binary package instead of a libcurl package. The SSL-enabled packages are required to use the ECaccess Web Services.
...
Environment
You need to ensure the following environment variables are set with the correct values:
...
If you don't want or can't setup these environment parameters then just replace $ECACCESS_URLV2
and $ECACCESS_OPTS
by their contents in the rest of the document.
...
Input/output
For each ECaccess Service available an example is given in the rest of this document with the CURL syntax to use, the list of parameters and the expected output.
...
If you get an HTML document then that could be a problem with a proxy. In this case the HTML message should give you an indication of what the problem is.
6.4 Authentication
...
Authentication
Certificates
Accessing the ECaccess Web Services API requires a valid certificate. Certificates can be created with the CURL command
...
In this request just replace uid by your ECMWF identifier and XXXXXXXX by your PASSCODE obtained from your security token. It generates a certificate in ".eccert.txt" in your user's home directory. The ECaccess Certificate is valid for one week and should be renewed after expiration.
...
Tokens
Requests to the ECaccess Web Services are performed by adding an HTTP header to the request which contains an Authentication token. Authentication tokens are generated for each session and require a valid certificate. To get an Authentication token (e.g. LOGIN) use the command
...
The Authentication token is now released and can't be used for any subsequent requests.
...
Cosinfo
Cosinfo provides ECMWF computer operations system information, such as scheduled or unscheduled downtime of servers, applications or hardware. The command
...
{ "cosinfo" : "********************************************************************\n* *\n* *\n* Welcome to AIX Version 5.3! *\n* *\n* *\n* Please see the README file in /usr/lpp/bos for information pertinent to *\n* this release of the AIX Operating System. *\n* *\n* *\n********************************************************************\n\n\nDear colleagues,\n\n\nThe following system sessions have been announced for\n\n Wednesday 5th of October 2012\n\n\n08:00-10:00 UTC DHS system session\nImpact: MARS and ECFS may be affected\n\n\n13:00-14:30 UTC ECPDS system session\nImpact: none\n\n\nHave a nice day,\nSylvia for Calldesk\n\n\n\nTo reread the message please use: more /etc/motd or cat /etc/motd\n\n===================================================================\n", "success" : "yes" } code=200
...
Gateways
To display the name of the Gateway you are connected to (please note this command does not need a token), command
...
{ "gateway" : { "name" : "forte.meteo.fr", "comment" : "HP-UX B.11.00 - Java HotSpot(TM) Server VM 1.4.2 1.4.2.08-050401-19:15-PA_RISC1.1 PA1.1 mixed mode Hewlett-Packard Company", "version" : "3.1.0_2007011001", "active" : false, "lastReport" : "Aug 22 13:15" }, "success" : "yes" } code=200
...
Operations
To list all the ECaccess Operations/Services available with the current token use
...
{ "operation" : { "name" : "submitJob", "comment" : "job submission", "duration" : "168h", "startDate" : "Sep 30 11:40", "validity" : 7, "endDate" : "Oct 07 11:40", "standard" : "168h" }, "success" : "yes" } code=200
...
Associations
All your ECtrans Associations for a Gateway (e.g. the "ecaccess.ecmwf.int" Gateway) can be listed with
...
Type | Name | Comment |
String | name | |
Boolean | active | default FALSE |
String | comment | |
String | grantedUserList | multiple users separated by a ',' |
String | data | |
String | directory | |
String | hostName | |
String | login | |
String | password | |
String | protocol |
...
Protocols
To list all the ECtrans Protocols supported by a Gateway (e.g. ecaccess.ecmwf.int) command
...
{ "protocol" : { "name" : "genericFtp", "value" : "$msuser[login]:$msuser[passwd]@$msuser[host]/$msuser[dir]$target", "comment" : "Generic FTP access from the gateway", "active" : true, "archive" : "${ecmwf.dir}/gateway/lib/ectrans", "module" : "ftp", "activeModule" : true }, "success" : "yes" } code=200
...
Files
The ECaccess files are in the form [domain:][/user-id/]path. Please refer to section 5.4 for more information on the ECaccess File System. To download a source ecaccess file, e.g. c2a:/tmp/test.tar.gz), use
...
This temporary file "tmp:roqZya" can be used to upload a temporary file (e.g. when submitting the input file for an ECaccess Job).
...
Jobs
To submit a new ECaccess Job, e.g. myjob.ksh which is a shell script without Loadleveler directives located in the ECMWF home directory:
...
{ "success" : "yes" } code=200
...
Events
To list all the ECaccess Events which are available to your ECMWF user identifier
...
{ "success" : "yes" } code=200
...
Queues
To list the available ECaccess Queues:
...
{ "queue" : [ { "name" : "pvwave", "comment" : "For jobs using PV-Wave - restricted access" }, { "name" : "timecrit", "comment" : "Suitable for time critical jobs - restricted access" (...) } ], "success" : "yes" } code=200
...
Transfers
In order to list all your ECtrans Transfers in the ECtrans Spool:
...