新华社供稿技术开放平台

接入方式

用户接入

用户按照API的规范拼装一个正确的URL，通过HTTP请求到API，就能够拿到用户自己需要的数据。

调用参数

调用API ，必须传入系统参数和应用参数(应用参数由于不同 API各自不同)。系统参数详细介绍如下；

1) 系统参数

名称	类型	是否必须	描述
method	string	是	API接口名称
session	string	是	分配给用户的session_key，通过登陆授权获取。
timestamp	string	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，例如：2014-01-01 20:23:30。
format	string	否	可选，指定响应格式。默认json,目前支持格式为json
app_key	string	是	分配给应用的app_key
v	string	是	API协议版本，例如:1.0。
sign	string	是	API输入参数签名结果
sign_method	string	是	参数的加密方法选择，可选值是：md5,hmac。

2) 应用参数

名称	类型	是否必须	描述
fields	string	是	应用参数的实际值，根据实际情况填写，不同接口应用参数不同

3) 签名sign

        调用API 时需要对请求参数进行签名验证，服务器也会对该请求参数进行验证是否合法的。方法如下：
        根据参数名称（除签名和图片）将所有请求参数按照字典顺序升序排序:key + value .... key + value       例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1，参数名和参数值之间的“=”去除，参数名之间用“&”，得到拼装字符串bar2&baz3&foo1
        系统同时支持MD5和HMAC两种加密方式:       md5：将secret 拼接到参数字符串头、尾进行md5加密后，再转化成大写，格式是：byte2hex(md5(secretkey1value1&key2value2&...secret))       hmac：采用hmac的md5方式，secret只在头部的签名后再转化成大写，格式是：byte2hex (hmac(key1value1&key2value2&..., secret))
      注：hex为自定义方法，JAVA中MD5是对字节数组加密，加密结果是16字节，我们需要的是32位的大写字符串，图片参数不用加入签名中测试工具使用的是HMAC的加密方式。

调用示例

调用API：aip.user.seller.get ，应用参数fields 返回nick ，使用系统默认MD5加密，因为各语言语法不一致，以下实例只体现逻辑。为便于说明，假设 app_key、secret、session 值均为 test。

1) 输入参数为:

        method= aip.user.seller.get
   timestamp=2013-05-06 13:52:03
       format=json
       app_key=test
       v=1.0
       sign_method=md5
       session=test

2) 按照参数名称字典顺序升序排列:

       app_key=test
       format=json
       method=aip.user.seller.get
       session=test
       sign_method=md5
       timestamp=2013-05-06 13:52:03
        v=1.0

3) 连接字符串:

连接参数名与参数值,并在首尾加上secret，如下：
testapp_keytest&fieldsnick&formatjson&methodaip.user.seller.get&sessiontest&sign_methodmd5&timestamp2013-05-06 13:52:03&v1.0test

4) 生成签名:

32位大写MD5值->F8787A580B8359414F5E3E7DCD66E35A

5) 组装HTTP请求:

将所有参数值UrlEncode并采用UTF-8编码，然后拼装，通过浏览器访问该地址（下面的地址是虚拟地址，请根据实际情况组装），即成功调用一次接口，如下：
http://api.xinhua-news.com/route/rest?sign=F8787A580B8359414F5E3E7DCD66E35A&timestamp=2013-05-06+13%3A52%3A03&v=1.0&app_key=test&method=aip.user.seller.get&format=json&session=test

注意事项

所有的请求和响应数据编码皆为utf-8格式，url里的所有参数值请做urlencode编码。如果请求的Content-Type是 application/x-www-form-urlencoded， http body里的所有参数值也做urlencode编码；如果是multipart/form-data格式，每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-8。

文档中心