You need to enable JavaScript to run this app.
导航
智能推荐平台
  • 文档首页
    • /
  • 智能推荐平台

下发回传接口（callback）

最近更新时间：2024.03.14 14:41:27

首次发布时间：2022.04.13 17:53:21

我的收藏

下发回传接口用于记录已推荐结果，在以后的推荐返回中对已推荐结果去重。
以电商行业举例，推荐接口返回推荐商品 id 列表 [1,2,3,4,5]，客户服务端判断商品 3 刚刚售罄，根据运营规则需要在第二位强制插入商品 10，最终将商品 id 列表 [1,10,2,4,5] 下发给客户端，那么客户侧需要同时将商品 id 列表 [1,10,2,4,5,3] 通过本接口上报。

注意

这里需要将被过滤的商品 3 以及强插商品 10 都返回，同时给不同的 item 附带相应的 extra 字段。 同一次下发的推荐结果必须一次性上报。

请求方法

HTTP POST

URL

《URL相关名词解释》

部署方式

Region

URL

SaaS

国内通用

https://api.byteair.volces.com/predict/api/${application_id}/callback

新加坡

https://byteair-api-sg1.byteintlapi.com/predict/api/${application_id}/callback

出海1

http://api-oversea1.byteair.volces.com/data/api/{application_id}/{topic}?method=write&stage={stage}

出海2

https://byteair-overseas-2.byteintlapi.com/data/api/{application_id}/{topic}?method=write&stage={stage}

私有化

/predict/api/{application_id}/callback（协议、域名等根据实际情况补充）

请求头

公共请求头部分详见《公共请求头说明》
接口额外请求头：

参数

说明

示例

是否必传

Enable-Spm-Route

用于告知推荐服务是否开启 SPM 路由。开启了之后推荐服务会根据请求携带的 SPM 将请求路由到绑定的栏位处理逻辑中。开启 SPM 路由的时候需要确保请求中的 SPM 是有效的 SPM，且已经绑定了栏位。否则服务端会返回错误。

true

否

请求体

参数

参数
类型
是否必传
描述
uid
string
是
用户id。
scene
string
是
callback对应的推荐场景，非特殊情况下均为default。
items
object list
是
需要回调的物品列表。
predictRequestId
string
否
强烈建议传输。当前callback请求对应的predict请求的Request-Id。例如：调用推荐接口时候的Request-Id为hr3sd12ui23478sd，那么对应的下发回传请求的此参数需填写为hr3sd12ui23478sd。如果此参数未填写，字节侧会尝试使用header里的Request-Id来匹配寻找对应的predict请求。
context
string
是
上下文信息

注意

一个推荐请求应该仅对应一个callback请求。如果同一个predictRequestId出现两次callback请求，容易引起预期外的结果。

示例

{
    "uid":"uid1",
    "scene":"default",
    "items":[
        {
            "id":"item_id1",
            "pos":"position1",
            "extra":"{\"reason\":\"exposure\"}"
        },
        {
            "id":"item_id2",
            "pos":"position2",
            "extra":"{\"reason\":\"filter\"}"
        }
    ],
    "predictRequestId":"ds12ad61hnwo",
    "context":{
        "spm":"A$##$B$##$C",
        "feature":{
            "stringFeature":{
                "key":"value"
            },
            "intFeature":{
                "key":2
            },
            "floatFeature":{
                "key":3.5
            },
            "doubleFeature":{
                "key":3.51231
            },
            "stringArrayFeature":{
                "key":{
                    "values":[
                        "values1",
                        "values2"
                    ]
                }
            },
            "intArrayFeature":{
                "key":{
                    "values":[
                        1,
                        2
                    ]
                }
            },
            "floatArrayFeature":{
                "key":{
                    "values":[
                        1.1,
                        2.2
                    ]
                }
            },
            "doubleArrayFeature":{
                "key":{
                    "values":[
                        1.11111,
                        2.22222
                    ]
                }
            }
        },
        "extra":{
            "key1":"value1",
            "key2":"value2"
        }
    }
}

返回体

参数

参数
类型
描述
code
int32
不等同于http status，用于排查业务错误。成功情况下，在json结构的返回体中不包含该字段。
message
string
状态信息，默认"OK"，遇到错误会返回错误信息。
success
bool
success字段存在，且等于true的时候，请求才是成功的。含义比code更简单直接一些。

示例

{
    "message": "OK",
    "success": true
}