资源位对接技术文档

简介

本 API 用于从神策获取资源位下的推荐结果

调用地址

https://{recommend-domain}/api/v2/sfo/section/recommend?org_id={org_id}&access_token={access_token}

{recommend-domain} 在神策服务实施部署时结合实际情况确定，{org_id}、{access_token} 参数用于接口鉴权，部署完成后由神策提供

请求参数

请求头

参数名	参数类型	是否必需	样例值	备注
project-name	String	是	"production"	项目名称，由神策提供，具体名称可参考神策系统网址中的 project 参数值。

请求体

参数名	参数类型	是否必需	样例值	备注
section_id	String	是	"section_id_9989032969689"	资源位 ID
distinct_id	String	否	"100ff36a832edacd"	用户唯一标识，未使用「神策数界CDP」产品时传入，与 identity_id_map 参数互斥，两者只能存在一个。
identity_id_map	Object	否	{"$identity_login_id":"id_16859", "$identity_mobile":"15509299999"}	用户唯一标识，使用了「神策数界CDP」产品时传入，参数 key value 取值请对接时联系神策进行支持，与 distinct_id 参数互斥，两者只能存在一个。 SF 4.4.4+ 版本支持。
log_id	String	是	"WXCA059A3D84AF05C6"	请求唯一标识。由请求方生成, 用于串联推荐结果展示后产生的后续行为。
context_property	Object	否	{"city": "上海"}	当您需要更实时的用户属性来获取推荐结果时，可将对应属性设置到该参数中: eg: {"city": "上海"}
need_sticky_item	Bool	否	true、false	请求结果是否包含置顶物品。若本次请求需要传置顶物品，则为 true；若本次请求不需要传置顶物品，则为 false；默认为 false。列表资源位独有。
page_number	Int	否	0	当前查询页码。从 0 开始，0 代表第 1 页。默认值为 0。列表资源位独有。
page_size	Int	否	10	每页推荐结果数量。取值范围：1~200，超过 200 统一按照 200 截取，默认值为 20。列表资源位独有。
strategy_match_type	Int	否	0、1	策略匹配类型，取值 0、1 0 ：所有策略都进行匹配，应用于用户开启了个性化； 1 ：仅匹配全部受众的策略，应用于用户关闭了个性化。默认值为0。 SF 4.4.2+ 版本支持。
content_recommend_type	Int	否	0、1	内容推荐类型，取值 0、1 0 ：表示正常使用用户属性进行排序过滤和内容渲染，应用于用户开启了内容个性化； 1 ：表示排序过滤时不使用用户属性，使用前端配置的参数默认值进行内容渲染，应用于用户关闭了内容个性化。默认值为0。 SF 4.4.2+ 版本支持。

接口返回

参数名	参数类型	样例值	是否必然存在	备注
errcode	Int	0	是	状态码，具体取值参考下文「错误码」
errmsg	String	"success"	是	错误信息，具体取值参考下文「错误码」
data	Object		否	推荐结果信息，具体字段参考下文

data

参数名	参数类型	样例值	是否必然存在	备注
log_id	String	"WXCA059A3D84AF05C6"	是	请求唯一标识，基于请求生成
section_id	String	"section_id_505"	是	资源位英文名
total_count	Int	10	是	返回的推荐结果数
user_properties	Object	{"distinct_id":"zx_17", "age": "4"}	否，仅配置了资源位回传用户属性时存在	返回资源位配置的回传用户属性，请求用户无值时返回配置的默认值
section_properties	Object	{"section_prop":"abc"}	否，仅配置了资源位回传参数时存在	返回的资源位自定义属性
items	List	-	是，无数据时空集合	推荐结果列表，列表元素格式参考下文

items

参数名	参数类型	样例值	是否必然存在	备注
item_id	String	"1"	否	推荐结果唯一标识。列表资源位独有。
item_type	String	"video"	否	推荐结果类型。列表资源位独有。
origin_id	String	"1"	是	推荐结果所属选品组
experiment_name	String	"实验组"	否，开启试验时必然存在	实验分流标识，当开启了AB实验时，该字段表示实验组的名称，用于后续埋点上报。轮播资源位独有。
score	Double	1.0	-	由推荐规则中的排序规则所计算出来的用于物品排序的排序得分。列表资源位独有。仅用于神策调试验证用，请勿依赖该字段。
strategy_id	String	"50001234"	是	资源位下的运营策略 ID。
retrieve_version_id	String	"35"	是	资源位下的运营策略版本 ID。
strategy_name	String	"活跃用户专属策略"	否	资源位下的运营策略名称。对于置顶物品则无该参数。
strategy_type	String	"TOP_ITEM"	是	策略类型。 TOP_ITEM: 表示置顶物品 NORMAL: 表示非置顶内容
online_time	Long	1593805689840	轮播资源位时必然存在	上线时间。时间戳，轮播资源位独有。
offline_time	Long	1593805689840	轮播资源位时必然存在	下线时间。时间戳，若值为 0，则代表永不下线。轮播资源位独有。
rec_frame_site	Int	2	轮播资源位时必然存在	轮播资源位运营策略对应位置。轮播资源位独有。
priority	Int	1	轮播资源位时必然存在	轮播资源位运营策略对应优先级。轮播资源位独有。
material_properties	Object	-	轮播资源位时必然存在	物料元素信息，具体 key value 与业务配置相关。轮播资源位独有。
item_property	Object	-	列表资源位时必然存在	自定义回传参数的物品属性，具体 key value 与业务配置相关。列表资源位独有。

若接口返回字段比上述内容多，则多出的字段用于神策调试验证等，请勿用于业务依赖，接口对接信息总体以上述表格为准。

错误码

errcode	errmsg	描述
0	success	请求正常返回
10001	sever internal error	服务内部异常
10002	project not bind or not exist	项目未绑定或不存在
10003	invalid http msssage	请求数据格式有误
20001	metadata not exist or invalid	元数据错误，多是传值不对导致
20003	project name not specified	项目未指定
20004	user id not specified	用户标识未指定
9000001	unauthorized	鉴权失败，请联系神策客服人员确认

请求示例

列表资源位请求

# curl 请求调用示例
curl -X POST \ 
--header 'project-name: default' \
--header 'Content-Type: application/json' \
--data '{
    "log_id": "908be1be972ef8f01c5d17be425f77c1",
    "distinct_id": "USER_abc",
    "section_id": "section_id_3854906038434",
    "context_property": {
        "city": "上海"
    },
    "need_sticky_item": true,
    "content_recommend_type": 0,
    "strategy_match_type": 0,
    "page_number":0,
    "page_size": 2
}' \
'http://{recommend-domain}/api/v2/sfo/section/recommend?org_id={org_id}&access_token={access_token}'

# 返回值示例
{
    "errcode": 0,
    "errmsg": "success",
    "data": {
        "section_id": "section_id_3854906038434",
        "log_id": "908be1be972ef8f01c5d17be425f77c1",
        "total_count": 2,
        "items": [
            {
                "item_id": "item_9",
                "item_type": "fund",
                "item_property": {
                    "item_id": "item_9",
                    "item_type": "fund"
                },
                "score": 0.0,
                "origin_id": "36",
                "experiment_name": "",
                "retrieve_version_id": "36",
                "strategy_name": "",
                "strategy_id": "50000030",
                "strategy_type": "TOP_ITEM"
            },
            {
                "item_id": "item_2",
                "item_type": "fund",
                "item_property": {
                    "item_id": "item_2",
                    "item_type": "fund"
                },
                "score": 1.0,
                "origin_id": "11",
                "experiment_name": "",
                "retrieve_version_id": "35",
                "strategy_name": "默认策略",
                "strategy_id": "50000023",
                "strategy_type": "NORMAL"
            }
        ]
    }
}

轮播资源位请求

# curl 请求调用示例
curl -X POST \  
--header 'project-name: default' \
--header 'Content-Type: application/json' \
--data '{
    "log_id": "908be1be972ef8f01c5d17be425f77c1",
    "distinct_id": "USER_abc",
    "section_id": "section_id_2345659465392"
}' \
'http://{recommend-domain}/api/v2/sfo/section/recommend?org_id={org_id}&access_token={access_token}'


# 返回值示例
{
    "errcode": 0,
    "errmsg": "success",
    "data": {
        "section_id": "section_id_2345659465392",
        "log_id": "908be1be972ef8f01c5d17be425f77c1",
        "total_count": 2,
        "items": [
            {
                "priority": 2,
                "origin_id": "34",
                "experiment_name": "",
                "retrieve_version_id": "34",
                "strategy_name": "VIP用户策略",
                "strategy_id": "50000029",
                "strategy_type": "NORMAL",
                "online_time": 1709204558479,
                "offline_time": 0,
                "rec_frame_site": 1,
                "material_properties": {
                    "img_url": "http://xxx.com/img_a"
                }
            },
            {
                "priority": 3,
                "origin_id": "37",
                "experiment_name": "",
                "retrieve_version_id": "37",
                "strategy_name": "全部用户策略",
                "strategy_id": "50000031",
                "strategy_type": "NORMAL",
                "online_time": 1710746434494,
                "offline_time": 0,
                "rec_frame_site": 1,
                "material_properties": {
                    "img_url": "http://xxx.com/img_b"
                }
            }
        ]
    }
}