vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

Dotyczące

API (and. application programming interface) pozwala na bezpośrednie zapytania do VOS4O z twojego własnego programu. Możesz je wykorzystać do stworzenia swoje strony internetowej zawierającej przeskalowany model Układu Słonecznego lub skryptu wysyłającego zapytania i pobierającego wygenerowaną tabelkę oraz rysunki. Dostępne są dwie metody odpytujące serwis:

• HTTP request : odpytaj serwis przez nie-interaktywne programy takie jak wget, curl lub Javascript objekt XMLHttpRequest..
• Web Service : odpytaj serwis przez Web Service (WS) na podstawie protokołów SOAP+WSDL+HTTP protocols.

Używanie Używanie API jest darmowe i bez opłat dla celów typu non-profit (osobistych lub edukacyjnych). Skontaktuj się z nami jeśli planujesz napisanie własnego oprogramowania korzystającego z VOS⁴O w celu otrzymywania powiadomień dotyczących updatów.

Błędy lub zapotrzebowanie na nowe funkcjonalności mogą zostać zgłoszone przez bug tracker.

Definicja skali

Możliwe są trzy sposoby definiowania skali:

x:y

w celu definiowania mnożnika X/Y do zastosowania do wszystkich długości. Na przykład skala 1:1000000 (jeden na milion) podzieli przez jeden milion wszystkie odległości oraz średnice planet.

a(planet):x

W celu ustawienia skali w taki sposób że odległość do wybranej planety równa się x. Na przykład , jeśli parametr jednostka=m (metr), wtedy skala a(neptun):7.22 stworzy model Układu Słonecznego w którym odległość Słońce – Neptun wynosi 7.22 metra.

d(planet):x

W celu ustawienia skali w taki sposób że średnia wybranej planety równa się x. Na przykład jeśli parametr jednostka=m (metr), wtedy skala d(Ziemia):1 stworzy model Układu Słonecznego w którym średnica Ziemi wynosi 1 metr.

Opis wynikowej tabelki oraz rysunków

Tabelka wynikowa wygenerowane przez VOS⁴O podaje średnicę Słońca oraz planet a także odległości pomiędzy planetami i Słońcem w wybranej skali. Spłaszczenie orbity planet oraz ich średnie heliocentryczne długości ekliptyczne (w stopniach) są podane na wybraną datę.

Pierwszy rysunek wygenerowany przez VOS⁴O zawiera model Układu Słonecznego w skali zdefiniowanej przez zadane parametry. Planety są wykreślone na osi w skali logarytmicznej w poprawnych wzajemnych odległościach. Przy każdej planecie podana jest jej średnia oraz odległość do Słońca (w wybranej skali).

Na drugim rysunku przestawiony jest widok na Układ Słoneczny z góry. Każda planeta znajduje się na swojej orbicie na średniej heliocentrycznej długości ekliptycznej obliczonej na wybraną datę. Punktem odniesienia obliczonych długości jest średni punkt barana (lub średni punkt równonocy) reprezentowany symbolem γ.

Zapytanie HTTP

Przy pomocy nieinteraktywnych program takich jak (wget, curl), lub przy pomocy przeglądarki, odpytaj serwis za pomocą protokołu HTTP

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

w którym [parameters] jest listą parametrów (zdefiniowanych w tabeli 1) oddzielonych symbolem &. Jeśli żaden z parametrów nie jest ustawiony serwis używa domyślnych wartości opisanych w tabeli 1.

^* Jeśli typ MIME to VOTABLE, wtedy autoscale parametr wynosi 0 bez względu na podaną wartość.

Wynik zapytania HTTP składa się z tabelki oraz dwóch rysunków, sformatowanych jako HTML, VOTable/XML lub tekstu zgodnie z podanym MIME type (-mime parameter).

Przykłady zapytań :

• Układ Słoneczny w skali 1:1000000 (jeden na milion).
• Układ Słoneczny w którym odległość Słońce-Neptune wtnosu 7.22 metra.
• Układ Słoneczny w którym średnica Ziemi wynosi jeden metr.

Web service

Serwis VOS⁴O może być odpytywany przez Web Service na podstawie protokołów SOAP+WSDL+HTTP co pozwala na bezpośrednia interakcję pomiędzy twoim oprogramowaniem a serwisem.

Web Service URI :

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

Namespace :

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

WSDL:

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

SOAP header:

Name of the SOAP header : clientID

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

Method :

scale (inputArray)

Parametry wejściowe

Parametry wejściowe metody scale są pokazane w tabelce i muszą definiować zmienne opisane w tabeli 2.

^* Jeśli wybrany typ MIME to VOTABLE wtedy parametr autoscale jest wymuszony jako false bez względu na jego wartość.

Parametry wyjściowe

Wynikiem metody 'scale' jest obiekt z atrybutami :

'status'

status na podstawie kodów HTTP : 200 = ok, 400 = bad request, 404 = not found, 500 = internal error.

'ticket'

Znacznik czasu odpowiedzi.

'result'

Ciąg znaków zawierający wynikową tabelę oraz rysunki Układu Słonecznego w podanej skali.

Typ MIME

W zależności od wybranego typu MIME type, wynik zapodania podany jest jako :

votable

Dane w dokumencie XML oraz standardzie VOTable z IVOA

html

Dane w dokumencie HTML5

text

Dane w pliku tekstowym

Jak używać ?

Istnieją dwie metody użytkowania serwisu skalującego : przez program typu klient wysyłający zapytanie do serwera VOS⁴O oraz odbierający odpowiedź, lub przez przeglądarkę internetową lub oprogramowanie transferu danych takie jak curl lub wget. W ostatnim przypadku wykonaj w terminalu komendę:

$> curl "<URL>"

lub

$> wget "<URL>"

gdzie <URL> jest opisany w rozdziale HTTP request.

W celu napisania oprogramowania które odpytuje serwis VOS⁴O service, wybierz język który implementuje protokół SOAP. Poniżej przykład napisany w PHP:

// Client's ID: provide the name of your project or organisation
                $from = 'MyName';
// Input parameters
$param = array('scale' => 'd(Terre)=1.0',
               'autoscale' => true,
               'scalefactor' => 1.0,
               'unit' => 'm',
               'axis' => 'log',
               'lang' => 'pl-pl',
               '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);
}