XDOC服务器API手册(11.4.5)

通过该手册,用户可以将XDOC服务集成到自己的应用中。
XDOC以HTTP协议对外提供服务,支持GET和POST两种请求方式。参数加在服务地址后面进行传递。参数名和值必需用UTF-8进行编码,内容比较多时需要用POST方式调用,支持文件上传。内置参数以“_”开头,XDOC服务器根据_func参数的值做不同处理,_func参数的默认值为run。
XDOC的服务接口分为五部分:
  服务器信息
方法:招呼、关于
  账号口令
方法:账号、动态口令、注册、变更口令
  功能操作
方法:编辑、资源管理器、表单、参数表单、阅读、运行、转换、清除缓存
  存储管理
方法:
ID存储上传、ID存储下载、ID存储删除
新建目录、目录列表、文件列表、上传、下载、删除目录或文件、目录或文件是否存在
  数据处理
方法:数据查询、数据转换

1.   招呼

方法

_func=hi

可选参数

_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调,不为空时,_rformat强制为json

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "string" >
         <![CDATA[ ok ]]>
     </ result >
</ response >
JSON 
{
     "success" : true ,
     "result" :{
         "dataType" : "string" ,
         "value" : "ok"
    }
}
注:下面简称OK,不再赘述

失败返回值

XML
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "false" >
     < error > 错误信息 </ error >
     < cause >
         <![CDATA[ 错误原因 ]]>
</ cause >
</ response >
JSON
{
     "success" : false ,
     "error" : "错误信息" ,
     "cause" : "错误原因"
}
注:错误返回值类似,下面不再赘述。

示例

http://api.xdocin.com/xdoc?_func=hi

2.   关于

显示服务器版本及授权信息

方法

_func=about

可选参数

_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "string" >
         <![CDATA[ XDOC Server 10.9.0
XDOC
C417FE75634D
2014-03-21~2015-03-21
1/100 ]]>
</ result >
</ response >
JSON
{
     "success" : true,
"result" :{
         "dataType" : "string" ,
         "value" : "XDOC Server A.1.5\nXDOC\nC417FE75634D\n2014-03-21~2015-03-21\n1\/100"
    }
}

3.   账号

方法

_func=acc

可选参数

_key
账号口令
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "map" >
         < value   admin = "true"   />
     </ result >
</ response >
JSON
{
     "success" : true ,
     "result" :{
         "dataType" : "map" ,
         "value" :{
             "admin" : "true"
        }
    }
}

4.   动态口令*

注:名称后带*功能表示使用管理员账号可用。

方法

_func=dkey

可选参数

_key
管理员账号口令
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "string" >
         <![CDATA[ 动态key ]]>
     </ result >
</ response >
JSON 
{
     "success" : true ,
     "result" :{
         "dataType" : "string" ,
         "value" : "动态key"
    }
}

5.   注册

注: 只支持云服务

方法

_func=reg

可选参数

_mail
邮箱,账号信息会发送到该邮箱
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "string" >
         <![CDATA[ 管理员key,只读key ]]>
     </ result >
</ response >
JSON 
{
     "success" : true ,
     "result" :{
         "dataType" : "string" ,
         "value" : "管理员key,只读key"
    }
}

6.   变更口令*

注: 只支持云服务

方法

_func=ckey

可选参数

_key
管理员账号口令
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "string" >
         <![CDATA[ 管理员key,只读key ]]>
     </ result >
</ response >
JSON 
{
     "success" : true ,
     "result" :{
         "dataType" : "string" ,
         "value" : "管理员key,只读key"
    }
}

7.   编辑

打开编辑器创建或编辑XDOC文档,并保存到服务器。也可以管理服务器上已经部署的文档。

方法

_func=edit

可选参数

_key
账号口令
_xdoc
待编辑的文档,文档名称以“./”开头,如:_xdoc=./a.xdoc
可以用URI方式替代,如:a.xdoc?_func=edit
以“./_”开头表示ID存储
ID可以使用只读账号口令,否则使用管理员账号口令
使用该参数,为单文档编辑模式,不能新建、打开、另存文档,不能使用服务器视图。
_tdoc
模板,当_xdoc参数指定的XDOC不存在时,以此模板新建。
模板常量:text(文字)、table(表格)、page(页面)、
web(网页)、select(选择)
支持以“./”开头的服务器文档模板,支持XDOC的XML和JSON格式。
_locale
语言,可选值,zh_CN(中文,默认),en(英文)
_webstart
是否以Java Web Start方式启动编辑器,可选值:true,false(默认)
_xdocstart
是否以XDoc Start方式启动编辑器,可选值:true,false(默认)

成功返回值

显示设计器,如下图:

8.   资源管理器

管理服务器上部署的文档。

方法

_func=resource

成功返回值

显示资源管理器,如下图:

9.   表单

表单XDOC文件必须部署在XDOC服务器上。

方法

URI方式,如:XDOC文件为:a.xdoc,调用方式为:http://api.xdocin.com/a.form
复杂交互表单可以使用xdoc.js,通过API处理。

可选参数

_key
账号口令
_id
存储ID,扩展名为xdat,可以忽略 
指定id为XDOC存储模式,表单会自动读写XDOC存储中的数据。
_data
数据获取地址
_action
数据提交地址
_debug
&_debug=true,调试模式,用工具提示显示表单域的名称
_format
格式,可选值:flash,html,PC下默认flash,移动设备默认html
XDOC中定义的表单项
传入值
注:_id和(_data、_action)参数二选一。

成功返回值

Flash或html表单

10.   参数表单

根据XDOC中定义的参数,自动生成参数表单,用户可以输入值后运行。

方法

_func=pdoc
URI方式,如:XDOC文件为:a.xdoc,调用方式为:http://api.xdocin.com/a.pdoc

可选参数

_key
账号口令
_xdoc
XDOC
_format
格式,可选值:flash,html,PC下默认flash,移动设备默认html
XDOC中定义的参数
传入参数值

成功返回值

Flash或html参数表单

11.   阅读

打开阅读器,阅读指定的文档,用户也可以选择本地文件,在线阅读。
带参数的XDOC文件,会显示参数表单,用户可以输入参数后运行。

方法

_func=view

可选参数

_key
账号口令
_xdoc
XDOC
_format
格式,可选值:flash,html,PC下默认flash,移动设备默认html
_locale
语言,可选值,zh_CN(中文,默认),en(英文)

成功返回值

显示阅读器,如下图:

12.   运行

方法

_func=run
run为默认值,可以不填

可选参数

_key
账号口令
_xdoc
XDOC,支持以下格式
  XDOC服务器中的XDOC
以“./”开头,如:./a.xdoc
ID存储以“./_”开头
如:./_26aa9971e78547f682c50ce437105f1c.xdoc
可以用URI方式替代,如:a.xdoc?_func=run
  URL
XDOC模板文档URL地址,XDOC服务器中必需可连接访问。
格式支持:xdoc、json、docx、epub、txt、rtf。
支持DATAURI协议,可传递二进制数据。
  JSON文本
符合XDOC-JSON规范的JSON文本
  XML文本
符合XDOC-XML规范的XML文本
  HTML文本
用html标签括起来的html文本
如:<html><h1>Hello</h1></html>
  纯文本
以"text:"开头的文本
_xdata
符合XDOC模板中数据模型的数据,格式可以为json、xml、csv或指向数据的URL地址,该地址XDOC服务器必须能访问。支持用“./”开头,使用XDOC服务上的数据。
可以使用参数“_id”指向的存储替代_xdata。
_format
输出格式
支持:flash(默认)、pdf、s.pdf(数字签名PDF)、docx、epub、jar、svg、swf、html、txt、png、jpg、gif。
需要XDocStart支持的格式:
edit.xnlp(编辑)、view.xnlp(查看)、print.xnlp(打印)
_imgbit
图片位数,可选值:2、4、8、16、24(默认)、32 
格式为png、jpg、gif时有效,位数越大颜色约丰富,通常文件也越大。
_to
输出目标
  空(默认值)
调用客户端
成功返回文件流
  mail
发送邮件
如果mail协议中没有指定主题,用xdoc文档的标题元数据做主题
如果mail协议中没有指定内容,用xdoc文档的描述元数据做内容
成功返回OK
  ftp
上传到ftp服务器,可以不指定_format参数
成功返回OK
  http
以multipart/form-data格式上传到http服务器,并将http服务器的结果返回
  ID存储
格式:id:存储ID
如:id:26aa9971e78547f682c50ce437105f1c.pdf
以“a_”开始的ID为只读存储,只能一次性写入,不能修改
可以不指定_format参数
成功返回OK
  datauri
成功返回用DATAURI格式描述的文件内容
  打印机
格式:print:printer
printer指向的打印机必须连接到XDOC服务所在服务器
成功返回OK
_cache
是否启用缓存
  空(默认值)
不使用缓存
  true
使用缓存
  false
不使用缓存,并清除旧缓存。
_attachment
true,以附件形式下载文件,在浏览器中_to参数为空时有效,默认false
_filename
下载文件名称,在浏览器中_to参数为空时有效
_callback
JSON回调
XDOC中定义的参数
传入参数值

成功返回值

由“_to”参数决定

13.   转换

方法

_func=to

可选参数

_key
账号口令
_xdoc
XDOC
_format
输出格式
_to
输出目标
注:参数具体描述参见运行
_callback
JSON回调

成功返回值

由“_to”参数决定

14.   清除缓存

方法

_func=cremove
清除超出指定缓存时长的缓存

可选参数

_expire
缓存时长,单位分钟,默认30分钟
_callback
JSON回调

成功返回值

成功返回OK

15.   ID存储上传

方法

_func=sup

可选参数

_key
账号口令
_id
存储ID,格式为由小写字母和数字组成的字符串加扩展名,扩展名默认为xdat。不正确时,服务器会自动修复。以”a_”开头的ID为归档ID,只能一次性上传,不能修改。
如:26aa9971e78547f682c50ce437105f1c.pdf
_data
DATAURI或文本
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

OK

16.   ID存储下载

方法

_func=sdown
URI方式,如:26aa9971e78547f682c50ce437105f1c.pdf .s

可选参数

_key
账号口令
_id
存储ID
_attachment
true,以附件形式下载文件,在浏览器中有效,默认false
_filename
下载文件名称,在浏览器中有效
_callback
JSON回调

成功返回值

文件流

17.   ID存储删除

方法

_func=sremove

可选参数

_key
账号口令
_id
存储ID
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

OK

18.   新建目录*

方法

_func=mkdir

可选参数

_key
账号口令
_dir
目录
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

OK

19.   目录列表*

方法

_func=dirlist

可选参数

_key
账号口令
_dir
目录
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "rowset"    fields = "NAME " >
         < row   NAME = "a"   />
         < row   NAME = "b"   />
     </ result >
</ response >
JSON
{
     "success" : true ,
     "result" :{
         "dataType" : "rowset" ,
         "fields" : "NAME" ,
         "value" :[
            {
                 "NAME" : "a"
            },
            {
                 "NAME" : "b"
            }
        ]
    }
}

20.   文件列表*

方法

_func=filelist

可选参数

_key
账号口令
_dir
目录
_offset
文件列表偏移,与“_rows”参数以前使用,用于分页
如:&_offset=20&&_rows=10表示每页10条,取第3页
_rows
文件数量
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "rowset"   fields = "NAME,SIZE,DATE" >
         < row   NAME = "a.xdoc"   SIZE = "4.17KB"   DATE = "2014-12-03 16:25:49"   />
         < row   NAME = "b.xdoc"   SIZE = "41.58KB"   DATE = "2014-12-03 15:18:43"   />
     </ result >
</ response >
JSON
{
     "success" : true ,
     "result" :{
         "dataType" : "rowset" ,
         "fields" : "NAME,SIZE,DATE" ,
         "value" :[
            {
                 "NAME" : "a.xdoc" ,
                 "SIZE" : "4.17KB" ,
                 "DATE" : "2014-12-03 16:25:49"
            },
            {
                 "NAME" : "b.xdoc" ,
                 "SIZE" : "41.58KB" ,
                 "DATE" : "2014-12-03 15:18:43"
            }
        ]
    }
}

21.   上传*

方法

_func=up

可选参数

_key
账号口令
_dir
目录
_data
DATAURI或文本
_xdoc
XDOC,具体描述参见运行
使用该参数时,_dir参数的扩展名必须为xdoc
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

OK

22.   下载

方法

_func=down
URI方式,如:a.xdoc .d

可选参数

_key
账号口令
_dir
目录
XDOC文件可以用URI替代,如:a.xdoc?_func=down
_attachment
true,以附件形式下载文件,在浏览器中有效,默认false
_filename
下载文件名称,在浏览器中有效
_callback
JSON回调

成功返回值

文件流

23.   删除目录或文件*

方法

_func=remove

可选参数

_key
账号口令
_dir
目录
XDOC文件可以用URI替代,如:a.xdoc?_func=remove
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

OK

24.   目录或文件是否存在

方法

_func=exists

可选参数

_key
账号口令
_dir
目录
XDOC文件可以用URI替代,如:a.xdoc?_func= exists
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "string" >
         <![CDATA[ true ]]>
     </ result >
</ response >
JSON 
{
     "success" : true ,
     "result" :{
         "dataType" : "string" ,
         "value" : "true"
    }
}

25.   数据查询*

方法

_func=query

可选参数

_key
账号口令
_sql
查询sql
查询表单数据sql为:
select * from xdata('d1f165c1563942849476c107478798df')
d1f165c1563942849476c107478798df为文档id
_rformat
结果格式,可选值:xml(默认)、json、html
_callback
JSON回调

成功返回值

XML 
<? xml   version = "1.0"   encoding = "utf-8" ?>
< response   success = "true" >
     < result   dataType = "rowset"   fields = "_ID,_DATE " >
         < row   _ID = "2849476c1074"     _ DATE = "2014-12-03 16:25:49"   />
         < row   _ID = "165c15639428"     _ DATE = "2014-12-03 16:25:49"   />
     </ result >
</ response >
JSON
{
     "success" : true ,
     "result" :{
         "dataType" : "rowset" ,
         "fields" : "_ID,_DATE " ,
         "value" :[
            {
                 "_ID" : "2849476c1074" ,
                 "_DATE" : "2014-12-03 16:25:49"
            },
            {
                 "_ID" : "165c15639428" ,
                 "_DATE" : "2014-12-03 16:25:49"
            }
        ]
    }
}

26.   数据转换

方法

_func=xdata

可选参数

_key
账号口令
_id
存储ID
_xdata
XDATA数据,支持xml、json、csv三种格式,与_id参数互斥
_format
结果格式,可选值:xml(默认)、json、csv
_callback
JSON回调

成功返回值

_format参数指定的格式
目录
目录