全部产品

推送数据

更新时间:2020-10-28 17:27:09

相关概念

数据表

将数据根据数据属性分为不同的集合,称为数据表。不同场景对数据表的划分有所不同,一般来说需要用户表、内容表和行为表三张表。

文档

数据上传的基本单元为文档,文档结构如下(JSON格式):

  1. {
  2. "fields": {
  3. "field_1": "value_1",
  4. "field_2": "value_2"
  5. },
  6. "cmd": "add"
  7. }

其中 field_1、field_2 为内容字段,字段名和字段值根据 数据规范 填写,cmd为保留字段。

保留字段

字段名 取值范围 说明
cmd add、update、delete 新增、更新、删除文档,以下将进行详细介绍

注意:(1)add为新增操作,update为更新操作。
(2)add操作将新增一条文档,若已存在则替换原本文档。上报需提交主键以及全部字段信息。
(3)update操作将更新一条已有文档,确认主键后仅上报待更新字段即可。如果update一条不存在的文档,将需要等待一个内部调度周期才可生效,所以请不要将update操作误用为add。

内容字段

内容字段为文档的有效信息,请按照 数据规范 填写。

推送请求

一次请求可以包含一个数据表的多个文档,需要尽可能多的将多个文档放到一个请求,以提高性能(例如,累积800个文档或者间隔10秒钟触发一次推送请求),但不能超过800个。一次请求的多个文档的cmd字段可以不同。

配额限制

当user表或者item表上传数据过多,超出实例购买配额时,数据推送接口会返回超出限额错误码,详见本文档错误码说明页面。可以在一次推送请求里面,推送只包含delete命令字的文档,可以删除已经不需要的文档。

文档操作

文档中的cmd字段决定对数据表进行的操作。cmd为add,表示往数据表中添加文档,若数据表中已经存在相同的文档(数据表唯一标识字段完全相同的文档),已经存在的文档将会被删除。cmd为update,表示更新数据表中已经存在的文档。cmd为delete,表示删除数据表中已经存在的文档。各数据表唯一标识字段组合如下所示:

数据表 唯一标识字段组合
用户表 user_id、imei
内容表 item_id、item_type
行为表 无,行为表无法对文档进行更新和删除操作

一个推送文档,根据操作类型的不同,数据完整性要求也不同,具体如下:

操作类型 保留字段 内容字段
add 所有保留字段 数据表唯一标识字段组合以及本说明文档数据规范定义的必填字段
update 所有保留字段 数据表唯一标识字段组合以及本说明文档数据规范定义的必填字段
delete 所有保留字段 维护局表唯一标识字段组合

接口调用说明

一次接口调用,需要指定实例ID、数据表名和推送文档数据。其中推送文档数据为如下所示JSON数组表示:
注意:其中具体字段请自行参考数据规范进行添加或修改。

1.新增数据(add):

  1. //推送新增的item数据
  2. [
  3. {
  4. "cmd": "add",
  5. "fields": {
  6. "item_id": "1",
  7. "item_type": "article",
  8. "title": "感动中国的大学生,今成副书记",
  9. "content": "内容",
  10. "pub_time": "1590327038"
  11. }
  12. },
  13. {
  14. "cmd": "add",
  15. "fields": {
  16. "item_id": "2",
  17. "item_type": "article",
  18. "title": "感动中国的大学生,xxx",
  19. "content": "内容",
  20. "pub_time": "1590327038"
  21. }
  22. }
  23. ]
  24. //推送新增的行为数据
  25. [{
  26. "cmd": "add",
  27. "fields": {
  28. "item_id": "1024233",
  29. "item_type": "article",
  30. "bhv_type": "expose",
  31. "bhv_value": "1",
  32. "trace_id": "Alibaba",
  33. "trace_info": "1007.5911.12351.1002000:::::::",
  34. "scene_id": "testScene01,testScene02",
  35. "bhv_time": "1600852251",
  36. "user_id": "1"
  37. }
  38. },
  39. {
  40. "cmd": "add",
  41. "fields": {
  42. "item_id": "1024234",
  43. "item_type": "article",
  44. "bhv_type": "expose",
  45. "bhv_value": "1",
  46. "trace_id": "Alibaba",
  47. "trace_info": "1007.5911.12351.1002000:::::::",
  48. "scene_id": "testScene01,testScene02",
  49. "bhv_time": "1600852251",
  50. "user_id": "1"
  51. }
  52. }
  53. ]

2.更新数据(update),上报update消息需指定要修改的item_id+item_type+要更新的字段及内容,例:

  1. [
  2. {
  3. "cmd": "update",
  4. "fields": {
  5. "item_id": "2",
  6. "item_type": "article",
  7. "title": "更新后的item的title"
  8. }
  9. }
  10. ]

3.删除数据(delete),需指定要删除的item_id+item_type,例::

  1. [
  2. {
  3. "cmd": "delete",
  4. "fields": {
  5. "item_id": "2",
  6. "item_type": "article"
  7. }
  8. }
  9. ]

数据要求:

  1. 如果一次请求只有一个文档,也需要表示为json数组格式。
  2. 可以使用JSON的pretty风格,也可以使用不带换行和缩进的紧凑风格。

接口使用限制

  1. 单次请求不超过800个文档;
  2. 单次请求数据大小不超过1M;
  3. 单个文档不超过10K;
  4. 单个字段不超过5K。

参数说明

参数
类型
描述
是否必填
value
tableName
String
需要推送的表
用户数据:user
内容数据:item
行为数据:behavior
content
JSON
文档,详情见上文
content-cmd
String
content中必填字段,操作类型。详情见上文
add
update
delete

通过服务端SDK推送数据常见失败原因

详见:常见问题中数据对接期的第17个问题。

示例代码

  1. package com.aliyun.airec;
  2. import com.aliyuncs.DefaultAcsClient;
  3. import com.aliyuncs.airec.model.v20181012.PushDocumentRequest;
  4. import com.aliyuncs.airec.model.v20181012.PushDocumentResponse;
  5. import com.aliyuncs.http.FormatType;
  6. import com.aliyuncs.profile.DefaultProfile;
  7. import com.aliyuncs.profile.IClientProfile;
  8. public class PushDocument {
  9. private static final String accessKeyId = "输入您的 access key";
  10. private static final String accessKeySecret = "输入您的 access key secret";
  11. public static void main(String args[]) {
  12. //注意:下面的区域要和购买实例所在区域一致,如是北京区域,则填cn-beijing
  13. IClientProfile profile = DefaultProfile.getProfile("cn-hangzhou", accessKeyId, accessKeySecret);
  14. //注意:下面的区域要和购买实例所在区域一致,如是北京区域,则填("cn-beijing", "Airec", "airec.cn-beijing.aliyuncs.com")
  15. DefaultProfile.addEndpoint("cn-hangzhou", "Airec", "airec.cn-hangzhou.aliyuncs.com");
  16. DefaultAcsClient client = new DefaultAcsClient(profile);
  17. PushDocumentRequest request = new PushDocumentRequest();
  18. request.setAcceptFormat(FormatType.JSON);
  19. //填入实例id
  20. request.setInstanceId("airec-xxxx");
  21. //填入要上报的数据表名:user/item/behavior
  22. request.setTableName("item");
  23. String content = "要上报到智能推荐的json数据";
  24. request.setHttpContent(content.getBytes(), "UTF-8", FormatType.JSON);
  25. try {
  26. PushDocumentResponse response = client.getAcsResponse(request);
  27. System.out.println(response.getResult());
  28. } catch (Exception e) {
  29. e.printStackTrace();
  30. }
  31. }
  32. }