vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - 网络服务

关于

API (应用程序界面) 使您可以直接从您的软件访问 VOS⁴O。 您可用其创建个人网页来缩放太阳系，或者用于编写查询脚本以在专用程序中检索生成的 表格和图片。 我们提供了两种方法进行查询服务:

• HTTP访问 : 仅通过非交互式网络下载软件进行查询服务，例如 wget， curl 或者Javascript对象XMLHttpRequest。
• Web服务: 通过基于SOAP+WSDL+HTTP协议构建的Web服务形式访问 (WS)。

该API免费对外开放使用， 适用于任何非营利性 (个人或教育)用途。 如果您使用VOS⁴O提供的服务开发应用程序，我们强烈建议您与我们 联系 以接收到最新的信息。

请使用我们的问题跟踪器 来报告错误或提交新功能请求。

比例尺定义

我们提供了三种方法来定义比例尺:

x:y

通过设定一个应用于所有长度参数的乘积系数 X/Y来定义比例尺。 例如，比例尺为1:1000000（百万分之一）时。 所有行星的距离和直径都将除以一百万。

a(行星):x

通过设定某行星与太阳的距离长度x来定义比例尺。 例如，如果参数单位=m （米），则比例尺a(海王星):7.22 将创建一个太阳 – 海王星的距离为7.22米的太阳系视图。

d(行星):x

通过设定某行星的直径x来定义比例尺。 例如，如果参数单位=m (米)，则比例尺d(地球):1将创建一个地球直径为1米的太阳系视图。

输出图表描述

VOS⁴O生成的输出表格列出了在给定 比例尺下， 太阳和行星的直径和行星到太阳的距离，同时也列出了行星的轨道偏心率， 以及其在指定历元下的平均日心经度。

VOS⁴O生成的第一张图片为根据给定 比例尺生成的太阳系比例图。 行星按照其相对距离沿对数轴绘制，旁边显示了它的直径和到太阳的距离（按照比例缩放）。

第二张图片为太阳系的俯视图。 每个行星均位于其轨道的平均日心经度位置（按所指定的历元计算）。 日心经度以平均春分点为参考，由符号γ表示。

HTTP请求

使用非交互式Internet软件（如 wget, curl）， 或采用Internet浏览器，通过其HTTP接入点调用服务

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

其中[参数] 为参数列表(在 表1中定义)， 通过&分隔开。如果未设置任何参数，将采用表1中的默认值设置太阳系。

^* 如果MIME类型为 VOTABLE, 则autoscale参数将被强制设定为 0。

HTTP访问结果由一张表格 和两张图片呈现， 返回格式为HTML, VOTable/XML 或文本文件，具体通过MIME type (-mime参数设置)。

访问示例:

• 缩放比例 1:1000000 (百万分之一)的太阳系。
• 海王星至太阳的距离为7.22米 的太阳系。
• 地球直径为1米的太阳系。

Web服务

VOS⁴O可通过SOAP+WSDL+HTTP协议提供Web服务， 使您可通过您的私有应用直接访问我们的服务。

Web服务URI:

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

命名空间:

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

WSDL:

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

SOAP数据头:

Name of the SOAP header : clientID

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

方法:

scale (inputArray)

输入参数

scale的输入参数以及其定义, 见表2.

^* 如果MIME的类型为VOTABLE， 则autoscale参数将被强制设定为false。

输出参数

'scale'方法输出结果属性如下:

'status'

基于HTTP网页代码给出的输出状态: 200 = 正常, 400 = 错误的请求，404 = 页面未找到， 500 = 内部错误。

'ticket'

返回结果的时间戳。

'result'

包含太阳系缩放比例结果的表 和图片的字符串。

MIME type

通过选定MIME type， 结果将以以下格式显示:

votable

数据写入XML文档，格式遵循IVOA的VOTable标准。

html

数据写入HTML5文档。

text

数据写入纯文本文件。

如何使用?

提供两种使用服务的方式: 通过编写客户端向VOS⁴O服务器发送请求并接受结果， 或者通过Web浏览器或数据传输软件，如curl or wget来访问服务器。 在这种情况下，您应在终端执行:

$> 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' => 'zh-hans',
               '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);
}