API调用说明

更新时间：2015/09/18 访问次数：34567

1、调用介绍
2、API SDK方式调用示例
3、调用入口
4、调用参数
5、调用示例
6、注意事项

1、调用介绍

魔方API 调用为HTTP 方式，开发者可以按一定格式自行拼装HTTP请求进行API 调用，也可以基于我们提供SDK（SDK是由程序自动生成的代码包，包含了请求、加密生成sign等一些必要的功能，使用SDK进行调用非常简单，建议使用）进行API调用。以下内容主要为说明具体调用原理，具体可参考实例代码。

2、API SDK方式调用示例

API SDK已经集成了接口签名方法，只需要引入对应于的类文件，就可以直接调用接口了，开放平台API SDK下载：点击查看。

JAVA

   TaobaoClient client=new DefaultTaobaoClient(url, appkey, secret);  
  
TaeItemDetailGetRequest req=new TaeItemDetailGetRequest();  
  
req.setId("AAEkwBGKAAXszj-DOJ-KKVll");  
  
req.setFields("itemInfo,priceInfo,skuInfo,stockInfo,rateInfo,descInfo,sellerInfo,mobileDescInfo,deliveryInfo,storeInfo");  
  
TaeItemDetailGetResponse response = client.execute(req , sessionKey);

PHP

   $c = new TopClient;  
  
$c->appkey = appkey;  
  
$c->secretKey = secret;  
  
$req = new TaeItemDetailGetRequest;  
  
$req->setId("AAEkwBGKAAXszj-DOJ-KKVll");  
  
$req->setFields("itemInfo,priceInfo,skuInfo,stockInfo,rateInfo,descInfo,sellerInfo,mobileDescInfo,deliveryInfo,storeInfo");  
  
$resp = $c->execute($req, $sessionKey);

可以直接参考各个API文档中的SDK调用示例或者参考API测试工具。点击查看

3、调用入口

环境地址，即调用接口(API)时，都通过访问该地址，来获取该接口需要获取的数据

http请求地址：http://gw.api.taobao.com/router/rest

https请求地址：https://eco.taobao.com/router/rest

4、调用参数

调用API ，必须传入系统参数和应用参数。系统参数详细介绍如下；应用参数由于不同 API 各自不同，这里以 alibaba.security.yundun.spam.validate为例说明，更多请参考 API 文档。

1）系统参数

名称	类型	是否必须	描述
method	string	Y	API接口名称
timestamp	string	Y	时间戳，格式为yyyy-mm-dd HH:mm:ss，例如：2013-05-06 13:52:03。淘宝API服务端允许客户端请求时间误差为6分钟。
format	string	N	可选，指定响应格式。默认xml,目前支持格式为xml,json
app_key	string	Y	TOP分配给应用的AppKey ，创建应用时可获得
v	string	Y	API协议版本，可选值:2.0。
sign	string	Y	对 API 输入参数进行 md5 加密获得，详细参考如下 3、签名sign
sign_method	string	Y	参数的加密方法选择，可选值是：md5,hmac
session	string	N	TOP分配给用户的SessionKey(或 Access Token），通过登陆授权获取，方法参考用户授权介绍。API 文档上 “API用户授权类型” 标识为“需要”的，调用时均要传该参数

2）应用参数

名称	类型	是否必须	示例值	默认值	描述
content	String	必须	兼职赚钱加q12345		文本内容
app_id	String	可选	12345		业务Id, 可以根据业务Id在后台配置相应的反垃圾规则
user_id	Number	可选	12345	0	用户Id
configs	GarbageRuleInfo []	可选	查看		用户可以根据自己的需求自定义规则(也可联系开发平台人员在后台配置), 目前开放的规则:1、频率规则：限制分钟/小时/天的发布内容额次数, 如可以设置5分钟20条,1小时100条等。 2、相似文本规则：限制相似的文本发布的数量。 3、违禁词规则：对色情和政治敏感词进行拦截。4、关键词规则：对指定的关键词进行拦截，系统会识别同音字、拆分字等各种变异的关键词。5、垃圾文本识别规则：根据样本库识别垃圾文本信息，如骂人、兼职广告、店铺推广等, 目前系统有比较完善的样本库，业务方也可以根据自己的需求添加样本库。

3）签名sign（API SDK已经集成签名方法）

调用API 时需要对请求参数进行签名验证，TOP服务器也会对该请求参数进行验证是否合法的。方法如下：

根据参数名称（除签名和图片）将所有请求参数按照字母先后顺序排序:key + value .... key + value
例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1，参数名和参数值链接后，得到拼装字符串bar2baz3foo1

系统同时支持MD5和HMAC两种加密方式:
md5：将secret 拼接到参数字符串头、尾进行md5加密后，再转化成大写，格式是：byte2hex(md5(secretkey1value1key2value2...secret))
hmac：采用hmac的md5方式，secret只在头部的签名后再转化成大写，格式是：byte2hex (hmac(key1value1key2value2..., secret))

注：hex为自定义方法，JAVA中MD5是对字节数组加密，加密结果是16字节，我们需要的是32位的大写字符串，图片参数不用加入签名中测试工具使用的是HMAC的加密方式。

5、调用示例

API SDK已经集成调用接口的拼装加密逻辑，SDK示例： alibaba.security.yundun.spam.validate，应用参数URL: ;appkey: ;secret:

TaobaoClient client=new DefaultTaobaoClient(url, appkey, secret);

AlibabaSecurityYundunSpamValidateRequest req=new AlibabaSecurityYundunSpamValidateRequest();

req.setContent("兼职赚钱加q12345");

req.setAppId("12345");

req.setUserId(12345L);

List<GarbageRuleInfo> configs = new ArrayList<GarbageRuleInfo>();

GarbageRuleInfo configsItem = new GarbageRuleInfo();

configsItem.setId("frequent_rule");

List<GarbageRuleConfig> configs = new ArrayList<GarbageRuleConfig>();

GarbageRuleConfig configsItem = new GarbageRuleConfig();

6、注意事项

1）所有的请求和响应数据编码皆为utf-8格式，url里的所有参数值请做urlencode编码。如果请求的Content-Type是 application/x-www-form-urlencoded， http body里的所有参数值也做urlencode编码；如果是multipart/form-data格式，每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-8。
2）等公开信息查询类API建议用get请求，交易等隐私信息查询和修改类API建议用post请求。

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

开放平台

云盾魔方