文档

推送数据

更新时间:

概述

本篇文档将介绍如何向AIRec智能推荐服务推送实时数据,实时数据包括:实例启动后的所有对user、item、behavior表中数据的新增、修改、删除等操作。

AIRec智能推荐根据版本的不同,有两个推送实时数据的接口,二者推送数据逻辑相同,数据规范不同,需要根据版本选用,不可混用,接口分别为:

PushDocument:用于行业运营版、算法配置版进行实时数据推送。

PushColdStartDocument:用于冷启动版进行实时数据推送。

相关概念

数据表

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

文档

数据上传的基本单元为文档,文档结构是JSON格式,

保留字段

字段名

取值范围

说明

cmd

add、update、delete

新增、更新、删除文档,以下将进行详细介绍

重要
  1. add为新增操作,update为更新操作。

  2. add操作将新增一条文档,若已存在则替换原本文档。上报需提交主键以及全部字段信息。

  3. update操作将更新一条已有文档,确认主键后仅上报待更新字段即可。如果update一条不存在的文档,将导致生成一条脏数据,此数据并不可用,所以请不要将update操作误用为add。

  4. 如果想对某条数据的某个字段的值做删除操作,可以update该字段为none,不要update为空。

内容字段

内容字段为文档的有效信息,请按照 数据规范 填写,请注意冷启动版与其他版本数据规范不同。

推送请求

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

一次请求的多个文档的cmd字段可以不同。

配额限制

当user表或者item表上传数据过多,超出实例购买配额时,数据推送接口会返回超出限额错误码,详见本文档14、通过服务端SDK推动数据的常见错误

可以在一次推送请求里面,推送只包含delete命令字的文档,可以删除已经不需要的文档。

接口使用限制

  1. 单次请求不超过800个文档;

  2. 单次请求数据大小不超过1M;

  3. 单个文档不超过10K;

  4. 单个字段不超过5K;

  5. 注意不要在实例启动或重启未完成期间推送任何数据。

文档操作

文档中的cmd字段决定对数据表进行的操作。

cmd为add,表示往数据表中添加文档,若数据表中已经存在相同的文档(数据表唯一标识字段完全相同的文档),已经存在的文档将会被删除。

cmd为update,表示更新数据表中已经存在的文档。cmd为delete,表示删除数据表中已经存在的文档。各数据表唯一标识字段组合如下所示:

数据表

唯一标识字段组合

用户表

user_id

内容表

item_id、item_type

行为表

无,行为表无法对文档进行更新和删除操作

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

操作类型

保留字段

内容字段

add

所有保留字段

数据表唯一标识字段组合以及本说明文档数据规范定义的必填字段

update

所有保留字段

数据表唯一标识字段组合以及本说明文档数据规范定义的必填字段

delete

所有保留字段

数据表唯一标识字段组合

重要

add新增行为数据时,需要确保该条行为数据涉及的item和user数据已经上传,如未回传,需要在当天补齐,否则该条行为数据为无效数据,您可以在"控制台-数据诊断"处查看有问题的行为数据。

接口调用说明

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

1.新增数据(add):

//推送新增的item数据
[
    {
        "cmd": "add",
        "fields": {
            "item_id": "1",
            "item_type": "article",
            "title": "感动中国的大学生,今成副书记",
            "content": "内容",
            "pub_time": "1590327038",
            "status":"1",
            "scene_id":"test01",
            "weight":"100",
            "category_level":"3",
            "category_path":"12_1024_56",
            "tags":"新闻,感动中国"
        }
    },
    {
        "cmd": "add",
        "fields": {
            "item_id": "2",
            "item_type": "article",
            "title": "感动中国的大学生,xxx",
            "content": "内容",
            "pub_time": "1590327038",
            "status":"1",
            "scene_id":"test01",
            "weight":"1",
            "category_level":"3",
            "category_path":"12_1024_56",
            "tags":"感动中国"
        }
    }
]



//推送新增的行为数据
[{
        "cmd": "add",
        "fields": {
            "item_id": "1024233",
            "item_type": "article",
            "bhv_type": "expose",
            "bhv_value": "1",
            "trace_id": "Alibaba",
            "trace_info": "1007.5911.12351.1002000:::::::",
            "scene_id": "testScene01",
            "bhv_time": "1600852251",
            "user_id": "1"
        }
    },
    {
        "cmd": "add",
        "fields": {
            "item_id": "1024234",
            "item_type": "article",
            "bhv_type": "expose",
            "bhv_value": "1",
            "trace_id": "Alibaba",
            "trace_info": "1007.5911.12351.1002000:::::::",
            "scene_id": "testScene01",
            "bhv_time": "1600852251",
            "user_id": "1"
        }
    }
]

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

[
    {
        "cmd": "update",
        "fields": {
            "item_id": "2",
            "item_type": "article",
            "title": "更新后的item的title"
        }
    }
]

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

[
    {
        "cmd": "delete",
        "fields": {
            "item_id": "2",
            "item_type": "article"
        }
    }
]

数据要求:

  1. 如果一次请求只有一个文档,也需要表示为JSON数组格式。

  2. 可以使用JSON的pretty风格,也可以使用不带换行和缩进的紧凑风格。

参数说明

参数

类型

描述

是否必填

value

tableName

String

需要推送的表

用户数据:user

内容数据:item

行为数据:behavior

content

JSON

文档,详情见上文

content-cmd

String

content中必填字段,操作类型。详情见上文

add

update

delete

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

详见:14、通过服务端SDK推动数据的常见错误

示例代码

package com.aliyun.airec;

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.airec.model.v20181012.PushDocumentRequest;
import com.aliyuncs.airec.model.v20181012.PushDocumentResponse;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;

public class PushDocument {

    public static void main(String args[]) {
        //注意:下面的区域要和购买实例所在区域一致,如是北京区域,则填cn-beijing
        // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
        //强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。

        //本示例以将AccessKey保存在环境变量中来实现身份验证为例。
        IClientProfile profile = DefaultProfile.getProfile("cn-hangzhou", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

        //注意:下面的区域要和购买实例所在区域一致,如是北京区域,则填("cn-beijing", "Airec", "airec.cn-beijing.aliyuncs.com")
        DefaultProfile.addEndpoint("cn-hangzhou", "Airec", "airec.cn-hangzhou.aliyuncs.com");

        DefaultAcsClient client = new DefaultAcsClient(profile);

        PushDocumentRequest request = new PushDocumentRequest();
        request.setAcceptFormat(FormatType.JSON);

        //填入实例id
        request.setInstanceId("airec-xxxx");
        //填入要上报的数据表名:user/item/behavior
        request.setTableName("item");

        String content = "要上报到智能推荐的json数据";
        request.setHttpContent(content.getBytes(), "UTF-8", FormatType.JSON);

        try {
            PushDocumentResponse response = client.getAcsResponse(request);
            System.out.println(response.getResult());

        } catch (Exception e) {
            e.printStackTrace();  
        }
    }
}

推送数据及获取推荐结果的项目demo

详见:airec推送数据+获取推荐结果demo

  • 本页导读 (0)
文档反馈