菜单

资源位对接技术文档

简介

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

调用地址

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

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

请求参数

请求头

参数名参数类型是否必需样例值备注
project-nameString是"production"

项目名称，由神策提供，具体名称可参考神策系统网址中的 project 参数值。

请求体

参数名参数类型是否必需样例值备注
section_idString是"section_id_9989032969689"资源位 ID
distinct_idString否"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_idString是"WXCA059A3D84AF05C6"

请求唯一标识。由请求方生成, 用于串联推荐结果展示后产生的后续行为。

context_property

Object

否

 {"city": "上海"}

当您需要更实时的用户属性来获取推荐结果时，可将对应属性设置到该参数中:
eg: {"city": "上海"}

need_sticky_itemBool否true、false

请求结果是否包含置顶物品。若本次请求需要传置顶物品，则为 true；若本次请求不需要传置顶物品，则为 false；默认为 false。列表资源位独有。

page_numberInt否0当前查询页码。从 0 开始，0 代表第 1 页。默认值为 0。列表资源位独有。
page_sizeInt否10每页推荐结果数量。取值范围：1~200，超过 200 统一按照 200 截取，默认值为 20。列表资源位独有。
strategy_match_typeInt否0、1

策略匹配类型，取值 0、1

0 ：所有策略都进行匹配，应用于用户开启了个性化；
1 ：仅匹配全部受众的策略，应用于用户关闭了个性化。

默认值为0。

SF 4.4.2+ 版本支持。

content_recommend_typeInt否0、1

内容推荐类型，取值 0、1

0 ：表示正常使用用户属性进行排序过滤和内容渲染，应用于用户开启了内容个性化；
1 ：表示排序过滤时不使用用户属性，使用前端配置的参数默认值进行内容渲染，应用于用户关闭了内容个性化。

默认值为0。

SF 4.4.2+ 版本支持。

接口返回

参数名参数类型样例值是否必然存在备注
errcodeInt0是状态码，具体取值参考下文「错误码」
errmsgString"success"是

错误信息，具体取值参考下文「错误码」

data

Object
否推荐结果信息，具体字段参考下文

data

参数名参数类型样例值是否必然存在备注
log_idString"WXCA059A3D84AF05C6"是请求唯一标识，基于请求生成
section_idString"section_id_505"是资源位英文名
total_countInt10是返回的推荐结果数
user_propertiesObject

{"distinct_id":"zx_17", "age": "4"}

否，仅配置了资源位回传用户属性时存在

返回资源位配置的回传用户属性，请求用户无值时返回配置的默认值

section_propertiesObject

{"section_prop":"abc"}

否，仅配置了资源位回传参数时存在返回的资源位自定义属性
itemsList-是，无数据时空集合推荐结果列表，列表元素格式参考下文

items

参数名参数类型样例值是否必然存在备注
item_idString"1"否推荐结果唯一标识。列表资源位独有。
item_typeString"video"否推荐结果类型。列表资源位独有。
origin_idString"1"是推荐结果所属选品组
experiment_nameString"实验组"否，开启试验时必然存在

实验分流标识，当开启了AB实验时，该字段表示实验组的名称，用于后续埋点上报。轮播资源位独有。

scoreDouble1.0-

由推荐规则中的排序规则所计算出来的用于物品排序的排序得分。列表资源位独有。

仅用于神策调试验证用，请勿依赖该字段。

strategy_idString"50001234"是资源位下的运营策略 ID。

retrieve_version_id

String"35"是资源位下的运营策略版本 ID。
strategy_nameString"活跃用户专属策略"否资源位下的运营策略名称。对于置顶物品则无该参数。
strategy_typeString"TOP_ITEM"是

策略类型。

TOP_ITEM: 表示置顶物品

NORMAL: 表示非置顶内容

online_timeLong

1593805689840

轮播资源位时必然存在上线时间。时间戳，轮播资源位独有。
offline_timeLong1593805689840轮播资源位时必然存在下线时间。时间戳，若值为 0，则代表永不下线。轮播资源位独有。
rec_frame_siteInt2轮播资源位时必然存在轮播资源位运营策略对应位置。轮播资源位独有。
priorityInt1轮播资源位时必然存在

轮播资源位运营策略对应优先级。轮播资源位独有。

material_propertiesObject-轮播资源位时必然存在物料元素信息，具体 key value 与业务配置相关。轮播资源位独有。
item_propertyObject-列表资源位时必然存在自定义回传参数的物品属性，具体 key value 与业务配置相关。列表资源位独有。

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

错误码

errcodeerrmsg描述
0success请求正常返回
10001sever internal error服务内部异常
10002

project not bind or not exist

项目未绑定或不存在
10003invalid http msssage请求数据格式有误
20001metadata not exist or invalid元数据错误，多是传值不对导致
20003project name not specified项目未指定
20004user id not specified用户标识未指定
9000001unauthorized鉴权失败，请联系神策客服人员确认

请求示例

列表资源位请求

# 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"
                }
            }
        ]
    }
}



上一个
数据采集方案说明
下一个
通道插件化简介
最近修改: 2024-12-27