注意:以下文档只适用于TOP接口,请谨慎使用!

文档中心 > 聚石塔

【 基础规则:】 

1、订单同步(数据推送)服务必须要先创建应用,适用于订单处理类的应用(如订单管理、ERP、商家后台系统);
 
2、对于非必须获取订单全部信息的应用,考虑数据安全问题,暂时无法对外提供(但保留用户可以申请的权利);
 
3、订单同步(数据推送)服务目前支持 张家口的专用网络  ,数据库版本仅支持以下:
 
"MySQL 5.5" , "MySQL 5.6" , "MySQL 5.7" , "POLARDB(MySQL 5.6)",
 
"SQLServer 2008r2" , "SQLServer 2016_ent_ha" , "SQLServer 2016_std_ha" , "SQLServer 2012_ent_ha" , "SQLServer 2012_std_ha"  

一、操作流程:

1、 开通数据推送服务

       开通数据推送服务之前,请先确保您的应用已经拥有“交易API”权限,并且已经购买聚石塔RDS数据库。

1.1)进入开放平台控制台,在控制台左侧选择“数据推送”,进入数据推送服务处理页面。

 1.2)阅读 使用说明费用说明,然后点击“立即开通”。(务必确保开通前已阅读费用说明

 1.3) 选择对应要开通数据推送的应用,或者点击左上角”切换应用“。

注意:应用要先获取相关API权限后,才可开通数据推送服务。API 权限组获取可参考

 1.4)选定应用,点击应用图标,“确认”开通数据推送服务。(请确保已阅读数据推送费用说明

  注意: ”未入驻“和”已禁用“的应用,是无法选择开通数据推送服务的。(详情看报错信息)如有疑问,可提交工单咨询。

2、同步设置

主要设置历史数据同步天数、数据保留时长、推送业务范围、历史订单推送写入限制、推送到库的字段。字段含义参考API文档中的介绍:

 交易相关字段:taobao.trade.fullinfo.get( 获取单笔交易的详细信息 ),API权限组:订单信息查询

 退款相关字段:taobao.refund.get( 获取单笔退款详情 ),API权限组:退款管理包

 商品相关字段:taobao.item.seller.get( 获取单个商品详细信息 ),API权限组:商品同步

 分销相关字段:taobao.fenxiao.orders.get( 查询采购单信息 ),API权限组:分销管理

介绍不清楚可以提交工单咨询

注意:

数据推送服务只同步API文档中的部分字段,同步设置中可看到目前支持推送的全部字段。

API文档中有介绍但是同步设置中不存在的字段,是暂不支持推送的,若要获取该字段数据请通过调用API获取。

3、数据库管理

添加推送库,选定要同步到哪台RDS,勾选后确认添加。RDS较多时可通过搜索实例名称的方式添加。

注意:数据推送服务对数据库版本有限制,不是所有版本RDS实例都支持开通数据推送的,可支持版本见本文开头介绍。

如果买错版本导致添加实例时无法看到RDS实例,可提交工单申请退款,重新购买符合要求的数据库实例。

如果一个appkey下有多个RDS使用数据推送,当其中1个RDS到期不再使用数据推送了,请在页面上停止该实例,否则将拖慢其他RDS的数据推送。

4、 商家管理

添加商家,选择推送库实例,输入已经授权的商家昵称,设置同步历史数据天数,将商家添加到对应推送的RDS下。

注意:添加商家时必须是已经授权的商家,授权点击查看详情

对于历史数据的天数,交易是按订单创建时间计算,其他业务线是按修改时间计算。

5、一键搜索

提供一键搜索功能,开发者可通过业务订单号快速查询推送情况。

6、sys_info库变更

isv 开发者对 sys_info 都是“只读”权限,无法进行“增删改”操作。若要对sys_info库做操作,都要提交变更申请。

选择变更类型、数据库实例、填写执行SQL语句,详述申请理由,提交sys_info变更申请,审核通过后,后台会执行变更操作。

7、自助推送

若有部分数据未推送或者未收到的情况,ISV开发者可以创建同步任务,自助补推。

二、通过API添加/删除用户方法

//添加用户

 JushitaJdpUserAddRequest request=new JushitaJdpUserAddRequest();
      request.setRdsName(
"xxxx");//xxxxrds实例名
     JushitaJdpUserAddResponse response=client.execute(request,"session_xxxx");//session_xxxx为用户授权sessionKey;

注:使用API的方式 添加用户,对应的API地址:点击查看

//删除用户
      JushitaJdpUserDeleteRequest request=
new JushitaJdpUserDeleteRequest();
      request.setUserId(0L);
//这里设置用户id
      JushitaJdpUserDeleteResponse response=
client.execute(request);

注:使用API的方式 删除用户,对应的API地址:点击查看

 如果用户已经存在,调用add接口只会改变路由关系,而不会重新推送历史数据。

 如果先调用delete接口,再调用add接口,则会重新推送历史数据(推送的历史数据天数按之前页面的设置天数,和sessionkey失效再生效的补单规则不一样)(如果前后的rds不同,添加add需要在delete之后10分钟再执行)。

三、订单同步服务表结构

订单同步服务数据推送到默认库sys_info(若是首次开通,等店铺订单生成后,RDS会自动创建sys_info库),该库中包含交易 JDP_TB_TRADE等表。订单推送表结构设计为:关键字段+Text大字段,其中关键字段的命名和API返回字段是一致的,一旦确定,就不会再改变。业务字段增加,只增加到Text大字段里。

1、sys_info库表结构

交易 JDP_TB_TRADE

名称

类型

长度

说明

tid

NUMBER

20

交易订单id

status

VARCHAR

64

交易状态

type

VARCHAR

64

交易类型

seller_nick

VARCHAR

32

卖家昵称

buyer_nick

VARCHAR

256

买家昵称

created

DATETIME

 

交易创建时间

modified

DATETIME

 

交易修改时间

jdp_created

DATETIME

 

数据推送的创建时间

jdp_modified

DATETIME

 

数据推送的修改时间

jdp_hashcode

VARCHAR

128

Jdp用来做数据校验的字段

jdp_response

MEDIUMTEXT(sqlserverTEXT)

 

API返回的整个JSON字符串,格式和API保持一致

(参看taobao.trade.fullinfo.get)

索引

(`seller_nick`,`jdp_modified`),

(`jdp_modified`),

(`seller_nick`,`modified`),

(`modified`)

 

退款 JDP_TB_REFUND

名称

类型

长度

说明

refund_id

NUMBER

20

退款单号

status

VARCHAR

64

退款状态

seller_nick

VARCHAR

32

卖家昵称

buyer_nick

VARCHAR

256

买家昵称

tid

NUMBER

20

主订单id

oid

NUMBER

20

子订单id

created

DATETIME

 

退款时间

modified

DATETIME

 

修改时间

jdp_created

DATETIME

 

数据推送的创建时间

jdp_modified

DATETIME

 

数据推送的修改时间

jdp_hashcode

VARCHAR

128

Jdp用来做数据校验的字段

jdp_response

MEDIUMTEXT

(sqlserverTEXT)

 

API返回的整个JSON字符串,格式和API保持一致

(参看taobao.refund.get)

索引

(`seller_nick`,`jdp_modified`),

(`jdp_modified`),

(`seller_nick`,`modified`),

(`modified`)

 

商品 JDP_TB_ITEM

名称

类型

长度

说明

num_iid

NUMBER

20

商品数字id

nick

VARCHAR

32

卖家nick

approve_status

VARCHAR

32

商品上传后的状态。onsale出售中,instock库中

cid

VARCHAR

256

商品类目ID

has_showcase

VARCHAR

32

橱窗推荐,true/false

has_discount

VARCHAR

32

支持会员打折,true/false

created

DATETIME

 

发布时间

modified

DATETIME

 

商品修改时间

jdp_created

DATETIME

 

数据推送的创建时间

jdp_modified

DATETIME

 

数据推送的修改时间

jdp_delete

NUMBER

2

0表示正常,1表示逻辑删除。当收到商品删除消息时,程序做逻辑删除

jdp_hashcode

VARCHAR

126

Jdp用来做数据校验的字段

jdp_response

MEDIUMTEXT(sqlserverTEXT)

 

API返回的整个JSON字符串,格式和API保持一致,但不包含商品描述字段

(参看taobao.item.seller.get)

索引

(`nick`,`jdp_modified`),

(`jdp_modified`),

(`nick`,`modified`),

(`modified`)

 

分销代销订单 JDP_FX_TRADE

名称

类型

长度

说明

fenxiao_id

NUMBER

20

分销流水号,分销平台产生的主键

tc_order_id

VARCHAR

32

主订单ID (经销不显示)

status

VARCHAR

64

采购单交易状态

supplier_username

VARCHAR

32

供应商在来源网站的帐号名

distributor_username

VARCHAR

32

分销商在来源网站的帐号名

created

DATETIME

 

采购单创建时间

modified

DATETIME

 

交易修改时间

jdp_created

DATETIME

 

数据推送的创建时间

jdp_modified

DATETIME

 

数据推送的修改时间

jdp_hashcode

VARCHAR

128

Jdp用来做数据校验的字段

jdp_response

MEDIUMTEXT(sqlserverTEXT)

 

API返回的整个JSON字符串,格式和API保持一致

(参看taobao.fenxiao.orders.get)

索引

(`supplier_username`,`jdp_modified`),

(`jdp_modified`),

(`supplier_username`,`modified`),

(`modified`)

  

分销经销订单 JDP_JX_TRADE

名称

类型

长度

说明

dealer_order_id

NUMBER

20

经销采购单编号

order_status

VARCHAR

64

采购单状态

supplier_nick

VARCHAR

32

供应商nick

applier_nick

VARCHAR

32

分销商nick

applied_time

DATETIME

 

申请时间

modified_time

DATETIME

 

修改时间

jdp_created

DATETIME

 

数据推送的创建时间

jdp_modified

DATETIME

 

数据推送的修改时间

jdp_hashcode

VARCHAR

128

Jdp用来做数据校验的字段

jdp_response

MEDIUMTEXT(sqlserverTEXT)

 

API返回的整个JSON字符串,格式和API保持一致

(参看taobao.fenxiao.dealer.requisitionorder.query)

索引

(`supplier_nick`,`jdp_modified`),

(`jdp_modified`),

(`supplier_nick`,`modified_time`),

(`modified_time`)

2、sys_info数据删除

超过设置的数据保留时长会自动删除,具体可以在”同步设置”查看设置数据保留时长的方法。

3、sys_info订单数据查询(轮询)代码示例

public static void doSyncToBiz(Connection con, String start, String end)
         
throws SQLException, ApiException {
      
// 这里以mysql库,查询交易表为例子
      String query = 
"select tid,jdp_response from jdp_tb_trade where jdp_modified >? and jdp_modified<? order by jdp_modified,tid";
      PreparedStatement sqlStatement = con.prepareStatement(query);
      sqlStatement.setString(1, start);
      sqlStatement.setString(2, end);
      ResultSet result = sqlStatement.executeQuery();
      
while (result.next()) {         
         String jdpResponse = result.getString(
"jdp_response");
         
// 把json转为API的返回对象
         TradeFullinfoGetResponse 
rsp = TaobaoUtils.parseResponse(
               jdpResponse, TradeFullinfoGetResponse.
class);
         
// TODO isv根据业务需要把相关字段更新到业务库
         
//
      }
   }

 

四、RDS慢SQL等问题解决

相信ISV们在使用云数据库RDS的时候,肯定遇到过慢SQL的一系列问题,我们如何能够快速的排查到原因?如何来优化SQL的性能?同样,我们在使用同步服务数据库的时候,也会遇到查询时因为索引问题慢,因为子查询导致查询慢,分页的问题等等,这么麻烦的事情我们的DBA根据实际经验积累,对这些问题进行了总结和归纳,更好的帮助ISV们优化SQL,更好的使用RDS以及数据同步服务。详细请下载:

双十一RDS最佳实践

同步服务数据库访问规范

五、常见问题 FAQ

1、为什么我的数据没有实时推送?
A:请确认您的应用是不是刚开通订单同步服务,历史数据需要一定的时间才能推送完成。

2、为什么之前数据推送正常,突然不再进行数据推送了?或者某个用户的数据忽然停止推送?
A:1)排查sessionkey是否失效,排查方法调用taobao.jushita.jdp.users.get( 获取开通的订单同步服务的用户 )查看;
      2)session失效后,怎么办? session失效后,此用户的推送暂停。
待用户重新授权后(期间不要删除用户),数据推送会自动恢复,期间数据也会补上来。

session失效超过1个月,用户将被删除,需重新添加 *用户是否存在:taobao.jushita.jdp.users.get( 获取开通的订单同步服务的用户 )

如果确认没有到期,提交工单联系聚石塔技术支持小二排查。

3、数据推送有延时,modified 与 jdp_modified 时间相差比较大,查看原因?
A:请按照下面的步骤排查下:
 之前用户授权是否有间断过,部分数据是通过对单的方式增加进来的;
 对于交易订单,子订单是否有更新,由于目前modified时间是针对主订单的,所以modified时间不变,后期会增加子订单的modified字段;
 排查推送的RDS的性能是否异常,或者是否出现磁盘已经满了;
 如果以上排查都没有问题的话,可以提交工单联系聚石塔技术支持小二

4、按记录的变化时间,来轮询查询记录,如何才能不漏单?
A:按变化时间倒序,然后从后向前翻页。
目的:防止在翻页过程中,有记录变化了,
原因:从后往前翻页"是防止漏单的必要条件,是防止已经读取过的数据变化了,导致后续数据整体迁移1位。
倒序::倒序+从后向前翻页还有个好处,能够记录已经读过的时间点,如果中断,下次可以从这个时间点开始读。

5、从sys_info同步数据,时间间隔一般是怎么设置的?
A:正常的数据是实时同步,延迟1~3S左右; 补单机制,交易的补单间隔时间5~20分钟 ( 商品和退款补单时间稍长,约为10~30)

6、15天之前的订单如果交易有更改会推送过来吗?
A:订单如果有修改,且在历史订单写入限制设置的时间范围内,就会实时推送,包含子订单的修改也会实时推送;

7、订单同步服务会不会有漏单的情况?
A:实时推送和补单的机制,如果实时数据漏了,自助推送可以确保不漏单;

8、以前订购的RDS可以选择用户,新订购的RDS选择不了用户呢?
A:当一个应用 下的数据会推送到多台RDS的时候,如果用户已经推送RDS1,需要先解除用户与RDS1的绑定,然后在把用户与RDS2关联,使用taobao.jushita.jdp.user.delete( 删除数据推送用户 ) 这个接口可批量解除关系,单个可通过页面直接操作;

9、在我的APPKEY下 选择不到我订购的RDS?
A:RDS是否已经关联到其它APPKEY下,原来的appkey不想关联那个rds了,请移除那个rds,而不仅仅取消启用,否则新的关联关系也建立不起来;

10、想知道 jdp_response 这个text里  解析后的每个字段的长度和类型?
A:目前没有 jdp_response 对应的API返回的字段长度;
关键字段的长度文档里是有的,非关键字段的长度,其实我们很想提供的,但API返回的字段并不是直接对应后端淘宝的数据库,有时候是几个数据库的字段合并起来返回一个值,除了那些非常基本的字段可以给出,其他的自行了解设置;

11、开启订单同步服务后是聚石塔系统自动创建一个数据库保存同步的订单数据还是可以指定放置某个数据库下面?
A:订单推送存放在系统自建的sys_info库里,isv有只读权限。

12、当订单同步服务启用后,是不是可以不用通过淘宝开放平台的接口来读取订单数据?可以直接读自己数据库中对应的表将最新的数据更新到商家系统当中?
A:订单同步服务会主动将订单数据及更新消息推送到RDS里;

13、发货等接口还是要继续通过淘宝开放平台接口来处理?
A:是的,目前订单同步只是同步数据且sys_info权限为只读,update操作都是通过接口来处理

14、订单同步的选择推送的用户数量有没有限制吗?
A:暂时没有限制,建议单应用最大不要超过50万

15、怎么查询我已经同步了哪些商家的数据?
A:查已使用数据推送的用户,可以用taobao.jushita.jdp.users.get( 获取开通的订单同步服务的用户 )来查询

16、问一下,订单同步服务数据推送及时性比较差,那下完单多久会推到RDS ?
A:99%的订单是3s以内推送,1% 5~20分钟内补上

17、订单同步服务与消息服务的区别?
A:消息服务实时性比较高,只包含部分的变化信息,完整的信息需要通过API来调用。详情参考消息服务使用介绍
订单同步服务实时性要慢于消息服务,但是数据较全和API返回数据相同;实时性要求特别高的不适合使用订单同步服务。

 

FAQ

关于此文档暂时还没有FAQ
返回
顶部