vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

A propos

API (Application Programming Interface) ermöglicht es direkt VOS⁴O von einer Computeranwendung oder einer Software abzufragen. Es ist somit möglich, eine persönliche Webseite zu erstellen, die das Sonnensystem skaliert, aber auch Skripten zu erstellen die den Dienst abfragen und die Tabelle und Bilder wiederherstellen, die in einem speziellen Program erzeugt wurden. Zwei Methoden stehen zur Verfügung, um den Service abzufragen:

• HTTP Abfrage : Einfach mit einem nicht interaktiven Internet-Download-Programm wie wget, curl oder mittels XMLHttpRequest mit Hilfe eines Javascripts.
• Web Service : Abfrage des Dienstes über seinen Webservice (WS) basierend auf den Potokollen SOAP+WSDL+HTTP.

Die Benutzung des API ist kostenlos für den persönlichen oder pädagogischen und nicht kommerziellen Gebrauch. Es wird dringend empfohlen uns zu kontaktieren, wenn sie eine Anwendung entwickeln, die den VOS⁴O nutzt um über Entwicklungen informiert zu werden.

Bitte verwenden Sie unser Meldesystem um eventuelle Fehlfunktionen zu melden oder um Verbesserungen vorzuschlagen.

Maßstabsdefiniton

Die Definition der Skala kann auf 3 Arten erfolgen :

x:y

um einen X/Y-Multiplikator anzugeben, der auf alle Längeneinheiten angewendet wird Zum Beispiel ermöglicht die Skala 1:1000000 (ein Millionstel), die Entfernungen und die Durchmesser der Planeten durch eine Million zu teilen.

a(Planet):x

die Skala auf den gegebenen Wert x der Entfernung eines gegebenen Planeten anzuwenden. Wenn zum Beispiel der Parameter Einheit=m (Meter) ist, dann ermöglicht die Skala a(neptune):7.22 ein Sonnensystem zu bilden, in dem die Entfernung Sonne-Neptun 7,22 Meter ist.

d(Planet):x

die Skala auf den gegebenen Wert x der Entfernung eines gegebenen Planeten beziehen. Wenn zum Beispiel der Parameter Einheit=m (Meter) ist, dann ermöglicht die Skala d(terre):1 ein Sonnensystem zu bilden, in dem der Durchmesser der Erde 1 Meter ist.

Beschreibung der Tabelle und der Bilder

Die vom VOS⁴O-Dienst generierte Tabelle gibt den Durchmesser der Sonne, die Durchmesser der Planeten und ihre Entfernung zur Sonne in der gewählten Einheit dar. Die Exzentrizitäten der Umlaufbahnen der Planeten sind ebenso gegeben wie ihre mittleren heliozentrischen Längen zu einer bestimmten Epoche, ausgedrückt in Grade.

Das erste vom VOS⁴O Dienst erstellte Bild stellt das Sonnensystem grafisch skaliert nach den gewählten Parametern dar. Neben jedem Planeten, der entlang einer logarithmischen Skalenachse bezüglich ihrer relativen Abstände angeordnet ist, werden sein Durchmesser und seine Entfernung zur Sonne entsprechend der gewählten Skala und Einheit berechnet.

Das zweite Bild zeigt das Sonnensystem von oben. Jeder Planet ist auf seiner Umlaufbahn entsprechend seiner heliozentrischen Länge positioniert, die für das gegebene Datum berechnet wird. Das Referenzsystem der Längengrade ist die Richtung des Frühlings-Schnittpunkts (oder die durchschnittliche Tagundnachtgleiche), das mit dem Symbol γ beschrieben wird.

HTTP Anfrage

Mit Hilfe eines nicht interaktiven Internet-Download Programm (wget, curl), oder über einen Internetbrowser:

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

wo [parameters] eine Liste von Parametern ist die in Tabelle 1 definiert ist, getrennt durch das Zeichen &. Wenn alle Parameter weggelassen werden, gibt der Dienst das skalierte Solarsystem basierend auf den in Tabelle 1 angegebenen Standardwerten zurück.

^* Wenn der angeforderte MIME Typ VOTABLE ist, dann is der Parameter echelleauto gleich 0 unabhängig von dem Eingabewert.

Die Antwort einer HTTP-Anfrage besteht aus einer Tabelle und einem Bild image in HTML Format, VOTable/XML oder in einem einfachen Textformat je nachdem welcher MIME Typ gewählt wurde (Argument -mime).

Beispiele für Abfragen :

• Das Sonnensystem im Maßtab 1:1000000 (ein Millionstel).
• Das Sonnensystem wenn die Entfernung Sonne - Neptune 7.22 Meter ist..
• Das Sonnensystem wenn der Durchmesser der Erde 1 Meter ist.

Web Service

Der VOS⁴O Service kann über ein Web-Service abgerufe werden, der auf SOAP+WSDL+HTTP Protokollen basiert und eine direkte Interaktion zwischen seiner eigenen Anwendung und dem Service ermöglicht.

Web Service URI :

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

Namensraum :

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

WSDL:

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

Kopfzeile SOAP :

Name des Elements des SOAP : clientID

Inhalt des SOAP Elements : array('from' => 'NomProjet', 'hostip'=>'')

Methode :

Skala (inputArray)

Eingabe Parameter

Die Eingabeparameter der Methode scale sind in einer Tabelle gruppiert und muss die beschriebenen Variablen in der Tabelle 2 definieren.

^* Wenn der angegebene MIME-Typ VOTABLE ist, muss der autoscale Parameter falsch angegeben werden egal welchen Wert man angibt

Ausgabe Parameter

Die Antwort der Methode 'scale' ist ein Objekt, das die folgenden Attribute enthält :

'status'

Der Status der Antwort, basierend auf den HTTP-Codes : 200 = ok, 400 = ungütige Anforderung, 404 = nicht gefunden, 500 = interner Fehler.

'ticket'

Zeitstempel der Antwort.

'Resultat'

Eine Zeichenfolge, die die Tabelle und die Bilder des skalierten Sonnensytems enthält

MIME Tye

Abhängig vom ausgewählten MIME-Typ wird die Antwort im folgenden Format zuruückgegeben:

votable

Die Daten werden in einem XML-Dokument gemüß VOTable Standard der l'IVOA geschrieben.

html

Die Daten werden in einem HTML5 Dokument bereitgestellt

text

Die Daten werden in ein Textdokument geschrieben.

Wie funktioniert das ?

Es gibt zwei Müglichkeiten, den Dienst bezüglich der Skalierung des Sonnensystems zu benutzen: Entweder eine Anfrage an den VOS⁴O senden und die Antwort abrufen oder sie verwenden einen Webbrowser oder ein Datenübertragungsprogramm wie curl oder wget. Führen sie in diesem Fall folgenden Befehl in einer Konsole aus :

$> curl "<URL>"

oder

$> wget "<URL>"

wo <URL> ist im Abschnitt HTTP Anfrage beschrieben.

Um ein Program zu schreiben das den VOS⁴O aufruft, müssen sie eine Sprache auswählen die das SOAP Kommunikationsprotokoll implementiert . Hier ein Beispiel eines in PHP geschriebenen Client:

// 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' => 'de-de',
               '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]],"\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);
}