vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Διαδυκτιακή υπηρεσία

Σχετικά

ο API (διεπαφή προγραμματισμού εφαρμογών) επιτρέπει την απευθείας αίτηση του VOS⁴O από μια τρίτη εφαρμογή ή λογισμικό. Έτσι είναι δυνατή η δημιουργία μιας προσωπικής ιστοσελίδας κλιμάκωσης του ηλιακού συστήματος, αλλά και η αποστολή εντολών για την ανάκτηση των δημιουργηθέντων πινάκων και εικόνων σε ειδικό πρόγραμμα. Υπάρχουν δύο μέθοδοι αίτησης της υπηρεσίας:

• Αίτηση HTTP : απλή αίτηση της υπηρεσίας με ένα μη διαδραστκό διαδυκτιακό πρόγραμμα λήψης, όπως π.χ. wget, curl ή ενός Javascript αντικειμένου σαν το XMLHttpRequest.
• Διαδυκτιακή υπηρεσία : αίτηση της υπηρεσίας μέσω της υπηρεσίας διαδυκτίου (WS) βασισμένη στα πρωτόκολλα SOAP+WSDL+HTTP.

Η χρησιμοποίηση της Διεπαφής είναι ελεύθερη και δωρεάν για προσωπική ή εκπαιδευτική και μη κερδοσκοπική χρήση. Συνιστάται να επικοινωνήσετε μαζί μας αν αναπτύξετε μια εφαρμογή που να χρησιμοποιεί την υπηρεσία VOS⁴O για να ενημερωθείτε των εξελίσεων.

Χρησιμοποιήστε το σύστημά μας αναφοράς περιστατικών για να αναφέρετε μια δυσλειτουργία ή να κάνετε αιτήσεις βελτίωσης της υπηρεσίας.

Ορισμός κλιμάκων

Υπάρχουν τρεις τρόποι να ορίσετε την κλίμακα:

x:y

Ορίστε έναν συντελεστή X/Y που θα πολλαπλασιάσει κάθε μήκος. Για παράδειγμα, η κλίμακα 1:1000000 (ένα εκατομμυριοστό) θα διαιρέσει κατά ένα εκατομμύριο όλες τις αποστάσεις και τις διαμέτρους των πλανητών.

a(πλανήτης):x

Ρυθμίστε την κλίμακα με βάση την απόσταση x του πλανήτη. Για παράδειγμα, εάν unit=m (μέτρα), τότε η κλίμακα a(Ποσειδώνας):7.22 δημιουργεί ένα ηλιακό σύστημα στο οποίο η απόσταση Ηλιος - Ποσειδώνας είναι 7.22 μέτρα.

d(πλανήτης):x

Ρυθμίστε την κλίμακα με βάση τη διάμετρο x του πλανήτη. Για παράδειγμα, εάν unit=m (μέτρα), τότε η κλίμακα d(Γη):1 δημιουργεί ένα ηλιακό σύστημα στο οποίο η διάμετρος της Γης είναι ίση με 1 μέτρο.

Περιγραφή του πίνακα και των εικόνων αποτελεσμάτων

Ο πίνακας αποτελεσμάτων που παράγεται από το VOS⁴O παραθέτει τη διάμετρο του Ήλιου και των πλανητών καθώς και την απόσταση μεταξύ των πλανητών και του Ήλιου, με βάση την επιλεγμένη κλίμακα. Υπολογίζονται επίσης η εκκεντρότητα των πλανητών και οι μέσοι όροι των ηλιοκεντρικών μηκών τους (σε μοίρες) στην επιλεγμένη ημερομηνία.

Η πρώτη εικόνα που παράγεται από το VOS⁴O αναπαραστά το ηλιακό σύστημα σε κλίμακα, σύμφωνα με τις καθορισμένες παραμέτρους. Οι πλανήτες αναπαραστούνται κατά μήκος ενός άξονα σε λογαριθμική κλίμακα στη σωστή σχετική απόσταση τους. Δίπλα σε κάθε πλανήτη αναφέρονται επίσης η διάμετρος και η απόστασή του από τον Ήλιο (σε κλίμακα).

Η δεύτερη εικόνα αναπαραστά το ηλιακό σύστημα όπως φαίνεται από πάνω. Κάθε πλανήτης βρίσκεται στο μέσο ηλιοκεντρικό μήκος του, υπολογιζόμενο στην επιλεγμένη ημερεομηνία. To σημείο αναφοράς για τα μήκη είναι η κατεύθυνση του μέσου εαρινού σημείου (ή της μέσης ισημερίας) συμβολιζόμενο από το σύμβολο γ.

Αίτηση ΗΤΤΡ

Με ένα μη διαδραστκό διαδυκτιακό πρόγραμμα λήψης σαν τα wget, curl, ή με ένα πρόγραμμα περιήγησης διαδικτύου (internet browser), αναζητήστε την υπηρεσία μέσω του σημείου πρόσβασης HTTP

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

όπου [parameters] είναι μία λίστα παραμέτρων (προσδιορισμένη στον πίνακα 1) διαχωρισμένων με το σύμβολο &. Εάν δεν είναι καταχωρημένη καμία παράμετρος, τότε η υπηρεσία χρησιμοποιεί τις προεπιλεγμένες αξίες που παρατίθενται στον πίνακα 1.

^*Εάν ο τύπος MIME είναι VOTABLE, η παράμετρος αυτόματης κλίμακας autoscale ορίζεται στο 0 ανεξάρτητα της αξίας της.

Το αποτέλεσμα μιας αίτησης HTTP αποτελείται από έναν πίνακα και δύο εικόνες, μορφοποιημένα σε HTML, VOTable/XML ή απλό κείμενο ανάλογα με τον καθορισμένο τύπο MIME (παράμετρος -mime).

Παραδείγματα αιτήσεων:

• Ηλιακό σύστημα στη κλίμακα 1:1000000 (ένα εκατομμυριοστό).
• Ηλιακό σύστημα όπου η απόσταση Ηλιος - Ποσειδώνας είναι 7.22 μέτρα.
• Ηλιακό σύστημα όπου η διάμετρος της Γης ησούται με ένα μέτρο.

Διαδυκτιακή υπηρεσία

Το VOS⁴O μπορεί να αναζητηθεί μέσω υπηρεσίας Web που να βασίζεται στα πρωτόκολλα SOAP+WSDL+HTTP και επιτρέπει άμεση διάδραση μεταξύ της δικής σας εφαρμογής και της υπηρεσίας.

Διαδυκτιακή υπηρεσία 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:

Όνομα του SOAP header : clientID

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

Μέθοδος :

scale (inputArray)

Εισαγόμενες παράμετροι

Οι εισαγόμενες παράμετροι των μεθόδων scale είναι οργανωμένες σε έναν πίνακα και πρέπει να ορίζουν τις μεταβλητές του πίνακα 2.

^* Εάν ο τύπος MIME είναι VOTABLE, η παράμετρος αυτόματης κλίμακας autoscale ορίζεται στο false ανεξάρτητα από της αξίας της.

Παράμετροι αποτελεσμάτων

Τα αποτελέσματα της μεθόδου 'scale' είναι ένα αντικείμενο (object) με τις ακόλουθες ιδιότητες (attributes):

'status'

στάτους της απάντησης, βασισμένο στους κώδικες HTTP: 200 = ok, 400 = bad request, 404 = not found, 500 = internal error.

'ticket'

Χρονοσφραγήδα (Timestamp) της απάντησης.

'result'

Σειρά χαρακτήρων που περιέχει τον πίνακα και τις εικόνες του ηλιακού συστήματος που υπολογίστηκε σε κλίμακα.

Τύπος MIME

Σύμφωνα με τον επιλεγμένο τύπο MIME, η απάντηση παρέχεται στους ακόλουθους μορφότυπους:

votable

τα δεδομένα είναι γραμμένα σε ένα έγγραφο XML με βάση τα VOTable στάνταρ του IVOA

html

τα δεδομένα είναι γραμμένα σε ένα HTML5έγγραφο

text

τα δεδομένα είναι γραμμένα σε ένα έγγραφο απλού κειμένου.

Πως;

Υπάρχουν δύο τρόποι χρησιμοποίησης της υπηρεσίας κλιμάκωσης: Γράφοντας μία εφαρμογή-πελάτης που να στέλνει αιτήσεις στο VOS⁴O server και να λαμβάνει και να μεταχειρίζεται την απάντηση, ή μέσω ενός Web browser ή λογισμικό μεταφοράς δεδομένων όπως το curl ή το wget. Σ'αυτήν την περίπτωση, πρέπει να εκτελέσετε σε ένα τερματικό (terminal):

$> curl "<URL>"

ή

$> wget "<URL>"

όπου το <URL> περιγράφεται στην ενότητα Αίτηση HTTP.

Για να γράψετε ένα λογισμικό που να κάνει αιτήσεις στην υπηρεσία VOS⁴O, επιλέξτε μία γλώσσα που να χρησιμοποιεί το πρωτόκολο SOAP. Παρέχουμε εδώ ένα παράδειγμα γραμμένο σε 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' => 'el-el',
               '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);
}