vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

Tietoa

API (application programming interface) mahdollistaa VOS⁴O-kyselyn luomisen suoraan omasta ohjelmastasi. Voit käyttää sitä luodessasi oman sivuston Aurinkokunnan skaalaamiseen, tai voit kirjoittaa ohjelman noutaaksesi taulukon ja kuvat. Kaksi metodia on käytössä kyselyiden luomiseksi palveluun:

• HTTP-pyyntö : Luo kysely yksinkertaisesti käyttämällä epäinteraktiivisia latausohjelmia, kuten wget, curl tai Javascript-oliota XMLHttpRequest.
• Web-palvelu : Lue kysely Web-palvelun kautta (WS), joka perustuu SOAP+WSDL+HTTP protokolliin.

APIn käyttäminen on vapaata ja ilmaista kaikkeen tuottoa tavoittelemattomaan tarkoitukseen (henkilökohtainen tai koulutuksellinen). Suosittelemme vahvasti ottamaan yhteyttä meihin, jos kehität applikaation käyttämällä VOS⁴O-palvelua saadaksesi tietoa päivityksistä.

Käytä bugi-seurantaa ilmoittaaksesi bugeista ja toivoaksesi uusia ominaisuuksia.

Mittakaavan määrittäminen

On kolme tapaa määrittää mittakaava:

x:y

Määrittämällä kerroin X/Y, jota käytetään kaikkiin pituuksiin. Esimerkiksi mittakaava 1:1000000 (miljoonasosa) jakaa kaikki planeettojen etäisyydet ja läpimitat miljoonalla.

a(planeetta):x

Määrittämällä mittavaava niin, että planeetan etäisyydeksi tulee x. Esimerkiksi, jos parametri yksikkö=m (metri), mittakaava a(neptunus):7.22 luo Aurinkokunnan, jossa etäisyys Aurinko – Neptunus on 7,22 metriä.

d(planeetta):x

Määrittämällä mittakaava niin, että planeetan läpimitta on x. Esimerkiksi, jos parametri yksikkö=m (metri), mittakaava d(maa):1 piirtää Aurinkokunnan, jossa Maan läpimitta on 1 metri.

Tulostaulukon ja -kuvien kuvaus

VOS⁴O:n luoma tulostaulukko listaa Auringon ja planeettojen parametrit sekä planeettojen ja Auringon väliset etäisyydet annetun mittakaavan mukaisesti. Planeettojen ratojen eksentrisyys ja heliosentriset keskilongitudit (asteina) raportoidaan myös.

Ensimmäinen VOS⁴O:n luoma kuva esittää Aurinkokuntaa asetettuna mittakaavaan annettujen parametrien mukaisesti. Planeetat piirretään logaritmiselle asteikolle oikeille suhteellisille etäisyyksille. Jokaisen viereen on merkitty sen halkaisija ja mittakaavan mukainen etäisyys Aurinkoon.

Toinen kuva esittää Aurinkokuntaa nähtynä ylhäältä. Jokainen planeetta sijaitsee kiertoradallaan heliosentrisellä keskilongitudilla laskettuna halutulle ajankohdalle. Longitudien referenssipiste on kevättasauspiste, jota esittää symboli γ.

HTTP-pyyntö

Käyttämällä epäinteraktiivisia Internet-sovelluksia, kuten wget, curl, tai Internet-selainta, kutsu palvelua sen HTTP:n kautta osoitteessa

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

jossa [parameters] on lista parametreja (määritelty taulukossa 1), jotka on eroteltu symbolilla &. Jos mitään parametreja ei ole ilmoitettu, palvelu asettaa arvoiksi taulukon 1 oletusasetukset.

^* Jos MIME-tyyppi on VOTABLE, autoscale parametri saa arvon 0 riippumatta annetusta arvosta.

HTTP-pyynnön tulos on yksi taulukko ja kaksi kuvaa, formaattina HTML, VOTable/XML tai yksinkertainen teksti, riippuen annetusta MIME-tyypistä (-mime parametri).

Pyyntöesimerkkejä:

• Aurinkokunta mittakaavassa 1:1000000 (yksi miljoonasosa).
• Aurinkokunta, jossa Aurinko - Neptunus etäisyys on 7,22 metriä.
• Aurinkokunta, jossa Maan läpimitta on yhden metrin.

Web-palvelu

VOS⁴O-palvelulle voi luoda kyselyitä Web-palvelun kautta SOAP+WSDL+HTTP-protokollien avulla, mikä mahdollistaa suoran vuorovaikutuksen oman applikaatiosi ja palvelun välillä.

Web-palvelun URI:

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

Nimiavaruus:

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

WSDL:

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

SOAP header:

SOAP headerin nimi : clientID

SOAP header : array('from' => 'NomProjet', 'hostip'=>'')

Metodi :

scale (inputArray)

Syöteparametrit

Scale-methodin syöteparametrit on ryhmitelty taulukkoon ja niiden täytyy määrittää muuttujat, jotka on kuvailtu taulukossa 2.

^* Jos MIME-tyyppi on VOTABLE, autoscale parametri saa arvon false riippumatta annetusta arvosta.

Tulosteen parametrit

Scale-metodin tuloksena on olio, jolla on seuraavat attribuutit:

'status'

tuloksen status, perustuen HTTP-koodeihin: 200 = ok, 400 = bad request, 404 = not found, 500 = internal error.

'ticket'

Tulosten aikaleima.

'result'

Merkkijono, joka sisältää tulos-taulukon ja kuvat skaalatusta Aurinkokunnasta.

MIME-tyyppi

Valitun MIME-tyypin mukaan, vastaus annetaan seuraavassa muodossa:

votable

data kirjoitetaan XML-tiedostoon IVOAn VOTable -standardin mukaan

html

data kirjoitetaan HTML5 -dokumenttiin

text

data kirjoitetaan tekstitiedostoon.

Kuinka?

Skaalauspalvelun käyttöön on kaksi tapaa: asiakasohjelman kirjoittaminen pyynnön lähettämiseksi VOS⁴O-serverille ja vastauksen vastaanottamiseksi ja hyödyntämiseksi, tai Web-selaimen tai datansiirto-ohjelman, kuten curl tai wget kautta. Näissä tapauksissa, kirjoita terminaaliin:

$> curl "<URL>"

tai

$> wget "<URL>"

jossa <URL> kuvaillaan osiossa HTTP-pyyntö.

Kirjoittaaksesi ohjelman kutsumaan VOS⁴O-palvelua, valitse ohjelmointikieli, joka käyttää kommunikointiprotokollaa SOAP. Seuraavana on esimerkkiohjelma kirjoitettuna kielellä PHP:

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

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// VOS4O name space
$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]].PHP_EOL; };
  } 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.PHP_EOL;
  }
} catch (SoapFault $fault) {
  trigger_error("SOAP Fault: {$fault->getTraceAsString()} 
      (faultcode: {$fault->faultcode}, 
       faultstring: {$fault->faultstring})", E_USER_ERROR);
}