vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Serviciul Web

Apropos

API-ul (interfaţa de programare aplicativă) permite interogarea directă VOS⁴O dintr-o aplicaţie sau un alt program informatic. Se poate astfel crea o pagină web personalizată de punere la scară a Sistemului Solar, împreună cu interogarea serviciului cu ajutorul unui script (serii de comenzi) și recuperarea tabelului și imaginilor generate într-un program specific. Sunt disponibile două metode pentru interogarea serviciului :

• Interogarea HTTP : interoghează serviciul cu un program de descărcare Internet non-interactiv cum ar fi wget, curl sau un obiect XMLHttpRequest al limbajului Javascript.
• Serviciu Web : interogarea serviciului via serviciul Web (WS) bazat pe protocoalele SOAP+WSDL+HTTP.

Utilizarea API-ului este liberă și gratuită în cazul unui uz personal, pedagogic, sau non-comercial. Este recomandat să ne contactaţi dacă dezvoltaţi o aplicaţie ce utilizează serviciul VOS⁴O pentru a fi informaţi de eventualele evoluţii ale serviciului.

Vă rugam să utilizaţi sistemul nostru de raport de incidente pentru a ne semnala o disfuncţionalitate sau pentru orice solicitare de ameliorare a serviciului.

Definirea scării

Definirea scării se poate face în trei moduri :

x:y

pentru a specifica un coeficient de multiplicare X/Y ce se va aplica la toate unităţile de lungime. De exemplu, scara 1:1000000 (un milionime) va împărţi la un milion distanţele și diametrele planetelor.

a(planetă):x

pentru punerea la scară a valorii x a distanţei până la o planetă. De exemplu, avem parametrul unite=m (metru); atunci scara a(Neptun):7.22 va permite realizarea unui Sistem Solar în care distanţa Soare – Neptun va fi 7.22 metri.

d(planetă):x

pentru punerea la scară a valorii x dată, a diametrului unei planete. De exemplu, dacă parametrul unitate=m (metru) atunci scara d(Tera):1 permite realizarea unui Sistem Solar în care diametrul Terei este de 1 metru.

Descrierea tabelului si a imaginilor obtinute

Tabelul generat de serviciul VOS⁴O conţine datele cu diametrul Soarelui, cu diametrele planetelor si cu distanţele lor până la Soare, puse la scară în unitatea de măsură aleasă. Tabelul mai conţine și excentricitaţile planetelor, împreună cu logitudinile medii heliocentrice la o epocă dată, exprimate în grade.

Prima imagine generată de serviciul VOS⁴O este o reprezentare a Sistemului Solar la scară în funcţie de parametrii alesi. Alături de fiecare planeta, de-a lungul unei axe gradate în scară logaritmică, ce respectă distanţele lor relative, pentru fiecare planetă este pus diametrul și distanţa ei de la Soare, în funcţie de scara aleasă și de unităţile utilizate.

A doua imagine prezintă Sistemul Solar văzut de deasupra. Fiecare planetă este pusă pe orbită în funcţie de propria ei longitudine medie heliocentrică calculată pentru momentul de timp ales. Referinţa longitudinilor este dată de direcţia punctului vernal mediu (echinocţiul mediu), materializat de simbolul γ.

Interogare HTTP

Prin intermediul unui program de descărcare Internet non-interactiv (wget, curl), sau prin intermediul unui navigator Internet, puteţi apela acest serviciu prin interogarea HTTP :

https://ssp.imcce.fr/webservices/vos4o/scale.php?[parameters]

unde [parameters] este o listă de parametri, definiţi în tabelul 1, separaţi între ei de caracterul &. Dacă nici un parametru nu este definit, atunci serviciul va trimite rezultatul interogării cu Sistemul Solar pus la scară cu valorile de iniţializare existente în tabelul 1.

^* Dacă tipul MIME ales este VOTABLE atunci parametrul echelleauto este 0 independent de valoarea propusă.

Răspunsul unei interogări HTTP este compus dintr-un tabel și o imagine, formatată în HTML, VOTable/XML sau în text simplu în conformitate cu tipul MIME ales (argument -mime).

Exemple de interogări :

• Sistemul Solar la scara 1:1000000 (o milionime).
• Sistemul Solar, dacă distanţa Soare - Neptun este de 7.22 metri.
• Sistemul Solar, dacă diametrul Terei este de 1 metru.

Serviciul Web

Serviciul VOS⁴O poate fi interogat via un serviciu Web bazat pe protocoalele SOAP+WSDL+HTTP ce permit o interacţiune directă între aplicaţia proprie utilizatorului și serviciul propus.

Web Service URI :

https://ssp.imcce.fr/webservices/vos4o/vos4o.php

Espace de nom :

https://ssp.imcce.fr/webservices/vos4o

WSDL:

https://ssp.imcce.fr/webservices/vos4o/vos4o.php?wsdl

Antet SOAP :

numele elementului din antetul SOAP : clientID

conţinutul antetului SOAP : array('from' => 'NumeProiect', 'hostip'=>'')

Metoda :

scale (inputArray)

Parametrii de intrare

Parametrii de intrare ai metodei scara sunt regrupaţi într-un tabel și trebuie să definească variabilele descrise în tabelul 2.

^* Dacă tipul MIME cerut este VOTABLE atunci parametrul autoscale este false independent de variabila iniţializată.

Parametri de iesire

Răspunsul la metoda 'scara' este un obiect ce conţine următoarele atribute:

'status'

statutul răspunsului, bazate pe codurile HTTP : 200 = ok, 400 = interogare defectuoasă, 404 = nu se găseste, 500 = eroare internă.

'ticket'

Data la care s-a efectuat răspunsul.

'result'

Un șir de caractere ce conţine tabelul și imaginile Sistemului Solar pus la scară.

Type mime

în conformitate cu tipul MIME selectional, răspunsul este returnat în formatul :

votable

datele sunt scrise într-un document XML în standard VOTable al IVOA

html

datele sunt scrise într-un document HTML5

text

datele sunt scrise în documentul de tip text.

Cum procedam ?

Serviciul de Sistem Solar la scară se poate utiliza în două moduri. O primă metodă ar fi scrierea unui client care să trimită o interogare la serverul VOS⁴O și care să recepţioneze și exploateze răspunsul. A două metodă este utilizarea unui navigator Web sau a unui program de transfer de date din categoria curl sau wget. In acest caz, executaţi linia de comandă :

$> curl "<URL>"

sau

$> wget "<URL>"

unde <URL> este descris în secţiunea interogari HTTP.

Pentru scrierea unui program client ce va utiliza serviciul VOS⁴O, trebuie ales un limbaj care are implementat protocolul de comunicaţie SOAP. Iată un exemplu de client scris în PHP:

// Client's ID: provide the name of your project or organisation or yourself
$from = 'MyName';
// Input parameters
$param = array('scale' => 'd(Terre)=1.0',
               'autoscale' => true,
               'scalefactor' => 1.0,
               'unit' => 'm',
               'axis' => 'log',
               'lang' => 'ro-ro',
               'mime' => 'html',
               'epoch' => 'now');

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// VOS4O namespace
$namespace = 'https://ssp.imcce.fr/webservices/vos4o';
// VOS4O WSDL
$uriwsdl = $namespace.'/vos4o.wsdl';

try {
  // Instantiate the client
  $client = new SoapClient($uriwsdl, array('exceptions'=>1));
  // SOAP header
  $header = array('from'=>$from, 'hostip'=>'');
  $client->__setSoapHeaders(array(
     new SOAPHeader($namespace, 'clientID', $header)
  ));  
  // Call the resolver method
  $response = $client->__soapCall('scale',array($param));
  // Display the results
  if ($param['mime'] == 'text') {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/plain");
    $res = split(';', $response->result);
    $nbr = count($res);
    $newkey = array_keys($res);
    for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],"\n"; };
  } else if ($param['mime'] == 'html') {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/html");
    echo $response->result;
  } else {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/xml");
    echo $response->result."\n";
  }
} catch (SoapFault $fault) {
  trigger_error("SOAP Fault: {$fault->getTraceAsString()} 
      (faultcode: {$fault->faultcode}, 
       faultstring: {$fault->faultstring})", E_USER_ERROR);
}