附录2-API接入-推荐服务请求

1. 推荐服务请求API

1.1 接口介绍

1)推荐服务请求格式

① HTTP Method:POST

② URL:https://nbrecsys.4paradigm.com/api/v0/recom/recall?requestID={请求ID}&sceneID={场景ID}&userID={用户ID}

③ Content-Type:application/json

④ Request Body:

  • 说明:对于不同推荐类型,推荐服务的请求body是有区别的。对于热门推荐个性化推荐,请求body中不需要携带额外的参数;对于关联推荐,需要在请求body中,把被关联的对象的参数传过来。
  • 举例:
热门推荐 个性化推荐 关联推荐
{} {} { "itemID":"1234567890", "itemTitle":"把培育时代新人的重任扛在肩上" }

2)推荐服务返回格式

① Return-Type:application/json

② Return Body:

  • 举例:

成功的返回

[
    {
        "item_id":"12345678990",
        "title":"把培育时代新人的重任扛在肩上",
        "content":"作为教育者,必须时刻把准时代方向,摒弃一切不合时宜的思想,始终坚持“五育并举”“六个下功夫”的要求,树好新时代教师“四有”标准,积极承担学生健康成长“四个引路人”责任,坚持不懈培育和弘扬社会主义核心价值观与大力弘扬民族精神、时代精...",
        "url":"http://item.btime.com/45bruvk0pr98bk99gaplsh0uolm",
        "category_id":"教育",
        "publish_time":"2019-04-03 14:54:38",
        "publisher_id":"当代商报",
        "tag":"中小学,教育",
        "cover_url":"http://p0.qhimg.com/t01debf66a8a2595437.png?size=306x212",
        "cover_url_size":"306x212",
        "score":0,
        "type":3,
        "context":"1VSG0nSgbaN/cfrrbulhwkH5Ce63mPYQf1vT1XYnBtFAjIw7lGc/a4GPNC+Z+kFb8ZWv",
        "item_read_cnt":994,
        "extra1":"",
        "extra2":"",
        "extra3":"",
        "extra4":""
    },
    {
        "item_id":"0987654321",
        "title":"中民金融执行总裁郑理破题穿越周期之术,再进“虚拟经济”下一城",
        "content":"作为中民投集团在香港的重要境外战略平台,中民金融(00245)近来高调转型数字金融只是起跑的发令枪,正如其执行总裁郑理所言,“帮助一家公司从0到1不是中民金融的长项,我们擅长的是帮助其从10成长到100、甚至1000”。",
        "url":"http://item.btime.com/45i5lt7oe3082093s7vunc1psfd",
        "category_id":"新闻",
        "publish_time":"2019-04-03 15:02:27",
        "publisher_id":"港股挖掘机",
        "tag":"虚拟经济,中民,郑理,总裁",
        "cover_url":"http://p4.qhimg.com/t013d042996144d68eb.jpg?size=1080x607",
        "cover_url_size":"1080x607",
        "score":0,
        "type":3,
        "context":"Zx0Hy8L/kMd6lSvudWezjke/okMhxGF3D/fCh51gAYwKFrWi1lLU1btXjAeBtNfeVfiolg9WzUFW9lb",
        "item_read_cnt":885,
        "extra1":"",
        "extra2":"",
        "extra3":"",
        "extra4":""
    },
    {
        "item_id":"8888999900",
        "title":"私物推荐:一个能拿来听歌的「智能录音笔」",
        "content":"因为工作的原因,我时常会用到录音笔(或者说是录音棒),但大多时候只是把它当做一个工具而不是什么让人「心潮澎湃」的电子产品。这次让我甘愿为索尼新发布的录音笔掏腰包的原因主要有两个:最近在VICE上看了一个,讲的是音乐人HotSurgar带着录音笔穿梭在城市的角落,收集采样声音素材并制作成极具想象力的音乐。在他手里,录音笔变成了一个极具创造性的工具。另外一个原因其实是为了听歌。手机听歌的便利性毋庸置疑",
        "url":"http://www.geekpark.net/news/214721",
        "category_id":"科技",
        "publish_time":"2019-04-04 11:22:57",
        "publisher_id":"",
        "tag":"索尼,录音笔",
        "cover_url":"https://imgslim.geekpark.net/uploads/imagefa3c5f0f92ecba36216189ac.jpg",
        "cover_url_size":"1080x720",
        "score":6,
        "type":5,
        "context":"6Y2150erV3kEfAUEjvrdPfuEiIpVBXatVNqLPSlSmG21zQbwQImneN+bAzrzAFsTyV+/x1HnRX2",
        "item_read_cnt":663,
        "extra1":"",
        "extra2":"",
        "extra3":"",
        "extra4":""
    }
]

失败的返回

{
    "code": 400,
    "info": "OK",
    "data": "INVALID_REQUEST_BODY"
}

1.2 Body字段介绍

1)推荐服务请求Body

  • 热门推荐
字段名称 字段类型 是否必传 释义 举例
page int 非必传 信息流场景下用来标记翻的页码。注意:如果需要获取置顶必推物料,该字段是必传的。关于置顶必推的设置,请见三、运营助手 page是从0开始的,即第一页时传"page":0。如果要获取置顶物料,page需传0,因为置顶物料只出现在第一页;如果要获取必推物料,page则按必推物料所出现的页码去传即可。
  • 个性化推荐
字段名称 字段类型 是否必传 释义 举例
page int 非必传 信息流场景下用来标记翻的页码。注意:如果需要获取置顶必推物料,该字段是必传的。关于置顶必推的设置,请见三、运营助手 page是从0开始的,即第一页时传"page":0。如果要获取置顶物料,page需传0,因为置顶物料只出现在第一页;如果要获取必推物料,page则按必推物料所出现的页码去传即可。
  • 关联推荐
字段名称 字段类型 是否必传 释义 举例
itemID string 必传 物料有且唯一的ID。 2834716231
itemTitle string 必传 物料的标题。 感动中国的大学生,今成副书记
page int 非必传 信息流场景下用来标记翻的页码。注意:如果需要获取置顶必推物料,该字段是必传的。关于置顶必推的设置,请见三、运营助手 page是从0开始的,即第一页时传"page":0。如果要获取置顶物料,page需传0,因为置顶物料只出现在第一页;如果要获取必推物料,page则按必推物料所出现的页码去传即可。

2)推荐服务成功返回Body

字段名称 字段类型 释义 举例
item_id string 物料有且唯一的ID。 2834716231
title string 物料标题。 感动中国的大学生,今成副书记
content string 物料文本内容,例如 简介/摘要/正文。 生于1982年的徐本禹是山东聊城人,家境贫寒的他在华中农业大学读书期间
url string 物料的链接地址。 http://www.pcUrl.com/xxx
category_id string 物料分类。 多级分类之间用英文逗号“,”进行分隔。例如1级分类——萌宠,2级分类——狗,则该字段的上传格式为“萌宠,狗”。1级分类之间用英文分号“;”进行分隔。如果某物料属于多个1级分类,例如既属于1级分类——萌宠,2级分类——狗,又属于1级分类——生物,2级分类——犬科,则该字段的上传格式为“萌宠,狗;生物,犬科”。
publish_time string 物料的发布时间。 2018-04-13 15:47:30
publisher_id string 物料发布者有且唯一的ID。 范式推荐
tag string 物料标签。 多个标签之间用英文逗号“,”进行分隔。例如“感动中国,官员”。
coverl_url string 物料封面图链接地址。 多个图片链接地址之间用英文分号“;”进行分隔。例如“https://660cfbc1.jpg;https://d667weghj.jpg”。
coverl_url_size string 物料封面图尺寸,格式为“长x宽”。 1080x720
score int 物料权重。 权重的范围是-10~10的整数。数值越大,权重越高,反之亦然。例如“9”。
type int 物料类型。 4
context string 推荐服务的标记。注意:该标记主要用于用户行为上报,行为上报时需要把该字段的内容原封不动返回去。 6Y2150erV3kx1HnRX2
item_read_cnt int *物料阅读/播放次数。 998
extra1 string 自定义字段1
extra2 string 自定义字段2
extra3 string 自定义字段3
extra4 string 自定义字段4

3)推荐服务失败返回Body

字段名称 字段类型 释义 举例
code string 状态码 400
info string 状态提示信息 OK
data string 失败的类型 INVALID_REQUEST_BODY

4)data(失败的类型)介绍

失败的类型(data) 释义 举例
INVALID_REQUEST_PARAMS 推荐服务接口请求的参数缺失或错误 sceneID漏写了;requestID格式不符合要求;等等。
INVALID_REQUEST_BODY 推荐服务接口请求的Body缺失或错误 body的花括号{}漏写了;等等。
RATE_LIMITED 同一userID调用推荐服务接口频次过高 同一userID调用推荐部分接口不要超过1次/秒。

1.3 代码示例

1)推荐服务请求

curl -X POST 
        'https://nbrecsys.4paradigm.com/api/v0/recom/recall?requestID=12345678&sceneID=111&userID=123456789' 
        -H 'Content-Type: application/json' 
        -d '{
            "itemID" : "999999991",
            "itemTitle" : "第四范式智能推荐"
        }'

2)推荐服务返回

[
    {
        "item_id":"12345678990",
        "title":"把培育时代新人的重任扛在肩上",
        "content":"作为教育者,必须时刻把准时代方向,摒弃一切不合时宜的思想,始终坚持“五育并举”“六个下功夫”的要求,树好新时代教师“四有”标准,积极承担学生健康成长“四个引路人”责任,坚持不懈培育和弘扬社会主义核心价值观与大力弘扬民族精神、时代精...",
        "url":"http://item.btime.com/45bruvk0pr98bk99gaplsh0uolm",
        "category_id":"教育",
        "publish_time":"2019-04-03 14:54:38",
        "publisher_id":"当代商报",
        "tag":"中小学,教育",
        "cover_url":"http://p0.qhimg.com/t01debf66a8a2595437.png?size=306x212",
        "cover_url_size":"306x212",
        "score":0,
        "type":3,
        "context":"1VSG0nSgbaN/cfrrbulhwkH5Ce63mPYQf1vT1XYnBtFAjIw7lGc/a4GPNC+Z+kFb8ZWv",
        "item_read_cnt":994,
        "extra1":"",
        "extra2":"",
        "extra3":"",
        "extra4":""
    },
    {
        "item_id":"0987654321",
        "title":"中民金融执行总裁郑理破题穿越周期之术,再进“虚拟经济”下一城",
        "content":"作为中民投集团在香港的重要境外战略平台,中民金融(00245)近来高调转型数字金融只是起跑的发令枪,正如其执行总裁郑理所言,“帮助一家公司从0到1不是中民金融的长项,我们擅长的是帮助其从10成长到100、甚至1000”。",
        "url":"http://item.btime.com/45i5lt7oe3082093s7vunc1psfd",
        "category_id":"新闻",
        "publish_time":"2019-04-03 15:02:27",
        "publisher_id":"港股挖掘机",
        "tag":"虚拟经济,中民,郑理,总裁",
        "cover_url":"http://p4.qhimg.com/t013d042996144d68eb.jpg?size=1080x607",
        "cover_url_size":"1080x607",
        "score":0,
        "type":3,
        "context":"Zx0Hy8L/kMd6lSvudWezjke/okMhxGF3D/fCh51gAYwKFrWi1lLU1btXjAeBtNfeVfiolg9WzUFW9lb",
        "item_read_cnt":885,
        "extra1":"",
        "extra2":"",
        "extra3":"",
        "extra4":""
    },
    {
        "item_id":"8888999900",
        "title":"私物推荐:一个能拿来听歌的「智能录音笔」",
        "content":"因为工作的原因,我时常会用到录音笔(或者说是录音棒),但大多时候只是把它当做一个工具而不是什么让人「心潮澎湃」的电子产品。这次让我甘愿为索尼新发布的录音笔掏腰包的原因主要有两个:最近在VICE上看了一个,讲的是音乐人HotSurgar带着录音笔穿梭在城市的角落,收集采样声音素材并制作成极具想象力的音乐。在他手里,录音笔变成了一个极具创造性的工具。另外一个原因其实是为了听歌。手机听歌的便利性毋庸置疑",
        "url":"http://www.geekpark.net/news/214721",
        "category_id":"科技",
        "publish_time":"2019-04-04 11:22:57",
        "publisher_id":"",
        "tag":"索尼,录音笔",
        "cover_url":"https://imgslim.geekpark.net/uploads/imagefa3c5f0f92ecba36216189ac.jpg",
        "cover_url_size":"1080x720",
        "score":6,
        "type":5,
        "context":"6Y2150erV3kEfAUEjvrdPfuEiIpVBXatVNqLPSlSmG21zQbwQImneN+bAzrzAFsTyV+/x1HnRX2",
        "item_read_cnt":663,
        "extra1":"",
        "extra2":"",
        "extra3":"",
        "extra4":""
    }
]
Copyright ©2017 4Paradigm All Rights Reserved            文件修订时间: 2019-10-09 11:23:23

results matching ""

    No results matching ""