You need to enable JavaScript to run this app.
导航

在线服务接口

最近更新时间2024.01.17 11:25:46

首次发布时间2023.10.08 10:43:10

1. 概述

在线服务接口:高QPS,低延迟,适合大的并发量且实时的场景,开启此接口需提前配置Redis资源,如未配置资源直接进行调用,则调用失败。在线服务配置入口:

2. 在线服务接口

2.1 获取用户属性/标签信息

注意

此接口实现了1.0版本里面的获取用户属性信息和获取用户标签信息,并增加新功能,允许查询传入非基准id的数据,前提是需要导入在线服务的待查询的id与基准id的idmapping的映射关系。

idmapping的配置可以参考 2.3 idmapping 高qps接口中的在线服务配置。

2.1.1 属性在线服务配置

点击“属性在线服务配置”进入该页面。在当前页面支持按照主体及业务系统筛选标签,需注意,可选择的业务系统必须是已经配置在在在线服务接口中的业务系统。

支持在列表页删除属性或者更新属性,即当上游属性更新后,需要手动更新配置的属性。

支持新增属性。支持选择主体及该主体下该操作用户有权限的属性,标签支持多选。
*注意:新增属性的数量与用户资源限制相关。

通过查询用户的基准id获取其标签

2.1.2 标签在线服务配置

点击“标签在线服务配置”按钮进入配置页面。在当前页面支持按照主体及业务系统筛选标签,需注意,可选择的业务系统必须是已经配置在在在线服务接口中的业务系统。

支持在列表页删除标签。

点击“新增标签”按钮进入配置页面,支持选择主体及该主体下的标签,标签支持多选。

*注意:新增标签的数量与用户资源限制相关。

2.1.3 接口调用

基本信息

生效版本1.18+
功能描述通过查询用户的基准id获取其属性
接口模块OnlineApi
接口名称GetUserProfileWithPrivacy
请求类型POST

请求参数

  • Query 参数
名称数据类型是否必选描述
ApiActionString对应“基本信息”中的“接口名称”
ApiVersionString版本号: 2023-02-10
  • Header
名称数据类型是否必选描述
AuthorizationString见《开发前必读》3.3中提到的签名
  • body
名称数据类型是否必选描述
projectstring租户code
profile_requestobject具体的参数如下

profile_request 里面的字段信息

名称数据类型是否必选描述
idstring用户的id
id_typeobject用户的id 类型,例如baseid, uid
properties整数数组属性id
tags整数数组标签id

ignore_illegal_data

int

1.21版本新增功能
0表示不做任何的过滤
1 表示过滤没有权限的标签和未导入到在线服务的标签

响应参数

名称数据类型描述
codeint64
messagestring
propertiesmap结构属性的结果,key 是属性id, value 是属性的值
tagsmap 结构标签的结果,key 是标签id, value 是标签的值

NOTE:

  1. 如果属性/标签的值为空,则返回的结果里面不包含此属性/标签的信息

响应样例

{
    "properties":{
        "1": "96", //1 代表的是属性id
        "2":"男"
        
    },
    "tags":{
        "23":"dwe",
        "45":"上海"
    }
    "code":0,
    "msg":"success"
}
  • 失败
{ 
  "data": "ERROR",
  "code": -1032
}

错误码

错误码错误消息描述解决方案
-10405对应appId: XXX 不在元数据中/根据XXX文档,将使用的appId对应的账户添加到待查询的接口的配置中
-10800包含无权限标签/需要将待查询的标签 授权给 appId 对应的账号

2.2 判断用户所在的分群「是否在指定分群中」

2.2.1 分群在线服务配置

点击“分群在线服务配置”进入该页面。在当前页面支持按照主体及业务系统筛选标签,需注意,可选择的业务系统必须是已经配置在在在线服务接口中的业务系统。

列表页展示分群名称,分群ID,以及导入状态,支持手动删除及更新。

点击列表右上角“新增分群”,可选择分群进行导入。

*注意:此处可选择的分群为分群列表中的所有分群,已导入的分群不可再进行选择,且可增加的分群数量,不超过系统支持的分群数量总和。

2.2.2 接口调用

基本信息

生效版本1.9+
功能描述给定一个 用户id, 一系列分群id, 返回用户所在的分群id
接口模块OnlineApi
接口名称QueryUserSeg
请求类型GET

请求参数

  • Query 参数
名称数据类型是否必选描述
ApiActionString对应“基本信息”中的“接口名称”
ApiVersionString版本号: 2023-02-10
idString用于查询所在分群的用户id
segIdsString逗号(半角符)分隔的分群ID,例如 1,2,3
  • Header
名称数据类型是否必选描述
AuthorizationString见《开发前必读》3.3中提到的签名
X-TenantString项目id

响应参数

名称数据类型描述
dataArray[String]用户所在的分群ID
codeint错误码

响应样例

{
    "data": [
        "1",
        "11"
    ]
    "code": 0
}

2.3 idmapping高qps接口

2.3.1 在线服务配置

在「OpenApi管理」功能模块中点击「在线服务接口」,在刷新后的页面右边点击「IDmapping在线服务配置」进入 「IDMapping在线服务配置」界面。

IDMapping - ID 在线服务

作用:将ID与OneID(又称基准ID BaseID)导入至高速查询引擎Tendis中,以保证高速查询能力和性能
操作:所有操作在 「IdMapping在线服务配置」页面内操作完成

  1. 点击【新增导入ID】

  2. 选择需要导入的ID对应的主体及ID类型,支持多个ID同时导入

*注:如已导入则无需重复导入

  1. 保存后返回列表,可以将ID导入逻辑手工更新,常规会每天定时更新导入

IDMapping -主体转换关系

作用:将A主体和B主体的转换关系导入至高速查询引擎Tendis中,以保证高速查询能力和性能

支持A主体的OneID到B主体的OneID直接转换,也支持关系中A主体的非OneID的ID类型转换为B主体的非OneID的ID类型,具体可以转的ID可以参考关系的配置

操作:

  1. 点击【新增导入主体转换关系】

  2. 选择需要转换的主体,然后根据主体拉出两者已经配置的关系

*注:导入转换关系时,会将主体中涉及到的ID类型也导入至告诉查询引擎Tendis中

将添加好的「IdMapping在线服务配置」绑定到「App管理」中的「对应服务账号」。

2.3.2 接口调用

基本信息

生效版本1.9+
功能描述查询不同的id类型之间的映射值
接口模块OnlineApi
接口名称GetIdMapping
请求类型POST

请求参数

  • Query 参数
名称数据类型是否必选描述
ApiActionString对应“基本信息”中的“接口名称”
ApiVersionString版本号: 2023-02-10
  • Header
名称数据类型是否必选描述
AuthorizationString见《开发前必读》3.3中提到的签名
  • Body
名称数据类型是否必选描述
idstring原始id类型的用户值

source_entity_name

string

需要转换的原始id类型的code, 例如 base_id, uid
source_entiy_name和target_entiry_name两个必须有一个是baseid

target_entity_name

string

目的id类型的code, 例如 base_id, uid
source_entiy_name和target_entiry_name两个必须有一个是baseid

interentity_strategy_id

int

跨主体转换策略id (1.20.2 新增字段)
(选择哪个跨主体转换策略,去转化主体A-主体B的关系,不同的转换策略,主体A-主体B的映射关系就会不一样)

idmapping映射说明

版本号映射和参数说明

1.19之前包含1.19

只支持同主体间的id映射
支持的映射关系:基准<->其他非基准类型 alt

source_entity_name 和target_entity_name 两个必须有一个是基准对应的code

1.20.2

支持同主体跨主体id映射

  1. 同主体查询 alt

source_entity_name 和target_entity_name 两个必须有一个是基准对应的code
interentity_strategy_id 不需要传值

  1. 跨主体查询 alt

1.21

支持同主体跨主体id映射

  1. 同主体查询 alt

interentity_strategy_id 不需要传值

  1. 跨主体查询 alt

interentity_strategy_id是跨主体转换策略id

请求样例

curl -v -S --location --request \
POST 'https://XXXXXX/openapi/online/v1/mapping/online/sync' \
--header 'X-BDPP-Id: XXXXXXXX' \
--header 'Authorization:Bearer XXX' \
--header 'Content-Type: application/json'  \
--data ':{
      "id":"12345678909",
      "source_entity_name":"phoneid",
      "target_entity_name":"baseid"
      }'

响应参数

名称数据类型描述
codeint64/
msgstring/
datastring映射后的值

响应样例

  • 成功
{
    "data": "123",
    "code": 0,
    "msg": "success"
}
  • 失败
{
    "data": "",
    "code": -1203,
    "msg": "xxxx"
}

2.4 判断用户是否命中实时规则

2.4.1 功能

提供高qps的在线服务接口:判断某个用户是否被实时更新的数据组成的规则命中

Tip: 目前CDP提供的分群及其相关接口相关数据为离线更新,本接口是独立于分群功能、对单点实时场景在线查询的补充。

2.4.2 操作说明

alt

Part 1 前置依赖

将需要用于规则引擎服务调用的所用标签、属性导入在线服务(tendis)

步骤示意图
  1. 进入控制台、标签/属性在线服务配置页面

2. 将规则需要使用的标签导入在线服务

Part2 规则配置

在区别于分群的页面,单独配置实时变更数据用于在线服务判断的规则

步骤示意图
  1. 进入控制台、规则引擎服务配置页面

  1. 选择已导入在线服务的标签、与属性创建规则

  1. 页面功能查询:单个用户是否属于某个规则(允许选择任意ID类型,在线返回结果)--可用于结果校验


2.4.3 接口调用

基本信息

生效版本1.16+(仅支持私部版本)
功能描述判断用户的id 是否命中规则
接口模块OnlineApi
接口名称CheckHitRealtimeRule
请求类型POST

请求参数

  • Query 参数
名称数据类型是否必选描述
ApiActionString对应“基本信息”中的“接口名称”
ApiVersionString版本号: 2023-02-10
tenantCodestring租户id
  • Header
名称数据类型是否必选描述
Authorizationstring见《开发前必读》3.3中提到的签名
  • Body参数(json格式)
名称数据类型是否必选描述
idstring用户的id
id_typestringid类型,如base_id,device_id
rule_ids[]int32规则id

响应参数

名称数据类型描述
codeint64
messagestring
rule_ids[]int32规则id, rule_ids 字段返回的是命中规则的id

响应样例

{
    "code": 0,
    "message": "success",
    "rule_ids":[1,2,3,4]
}
  • 失败
{
    "code": -1203,
    "message": "xxxx",
    "rule_ids":[]
}

2.5 查询用户是否命中分群v2版本

与2.2相比,支持传入用户id的idType类型与分群类型不一致但必须是在相同主体下,前提是开启idmapping导入,支持的场景见如下

用户idType类型分群类型是否支持是否是同主体说明
AA支持A 表示是系统的中某个IdType,用户idType类型和分群类型 是相同的IdType
基准类型非基准类型支持多个分群类型可以是不同的idType

非基准类型B

基准类型
或非基准类型B

支持

所有的分群只能是基准类型 或者与用户IdType 类型相同

非基准类型C非基准类型D不支持C和D 指代不同的非基准类型

基本信息

生效版本1.19+
功能描述根据用户是否命中分群的升级版本
接口模块OnlineApi
接口名称GetUserSegmentV2
请求类型POST

请求参数

  • Query 参数
名称数据类型是否必选描述
ApiActionString对应“基本信息”中的“接口名称”
ApiVersionString版本号: 2023-06-20
  • Header
名称数据类型是否必选描述
Authorizationstring见《开发前必读》3.3中提到的签名
  • 请求Body参数(json格式)
名称数据类型是否必选描述
tenant_codestring租户code
seg_data结构体seg_data定义如下

seg_data结构体的定义

名称数据类型是否必选描述
idstring用户id

id_type_code

string

用户的id类型,如baseid,uid,deviceid

segment_ids整数数组分群ids

响应参数

名称数据类型描述
codeint640 代表成功
messagestring
data整数数组用户命中的分群id

2.6 查询用户的行为(数据源和事件)和明细

基本信息

生效版本1.19+
功能描述查询用户的行为和明细数据
接口模块OnlineApi
接口名称GetUserDetailAndEvent
请求类型POST

请求参数

  • Query 参数
名称数据类型是否必选描述
ApiActionString对应“基本信息”中的“接口名称”
ApiVersionString版本号: 2023-06-20
  • Header
名称数据类型是否必选描述
Authorizationstring见《开发前必读》3.3中提到的签名
  • Body参数(json格式)
名称数据类型是否必填描述
tenant_codestring租户code

ignore_illegal

布尔类型

默认值是“false”。
含义:是否忽略未导入到在线服务的数据。
"false"代表当入参里面包含未导入的事件id或明细id,会直接报错。
"true":代表仅返回入参中导入到在线服务的事件id或明细id, 并在返回的结果中,将非法的id 放入到“illegal_input”中

data_req结构体定义如下2.6.1

2.6.1 data_req 结构体定义

名称数据类型是否必选描述
idstring用户id

id_type

string

用户的id类型,如baseid,uid,deviceid

event数组类型,元素是结构体event行为事件相关的参数,定义2.6.2
detail数字类型,元素是结构体detail明细相关的参数,定义2.6.3

2.6.2 event 结构体定义

名称数据类型是否必选描述
datasource_id整数数据源id

event_ids

整数数组

事件ids

start_time整数起始时间戳,单位 毫秒
end_time整数截止时间戳,单位 毫秒

need_properties

布尔类型

默认是false,
含义: 是否显示行为上报中用户的属性值

2.6.3 detail 结构体定义

名称数据类型是否必选描述
datasource_id整数数据源id
columnId整数数组明细ids
start_time整数起始时间戳,单位 毫秒
end_time整数截止时间戳,单位 毫秒

请求参数示例

{
"tenant_code":"1",
"ignore_illegal":true, //是否忽略未导入到在线服务的数据
"data_req":{
"id":"1",
"id_type":"uid",
 "event":[{
  "datasource_id":1,
  "event_ids":[1,2,3],
  "start_time":"1683880304000",//时间戳,单位到毫秒
  "end_time":"1683880305000", //时间戳单位到毫秒
  "need_properties":false  //显示用户的属性值
 }],
 "detail":[{
  "datasource_id":1,
  "columnId":[12,434,54],
  "start_time":"1683880304000",//时间戳,单位到毫秒
  "end_time":"1683880305000"//时间戳,单位到毫秒
 }]
}

}

响应参数

名称数据类型描述
codeint640 代表成功
messagestring
data结构体data定义如下2.6.4

2.6.4 data 结构体定义

名称数据类型描述
event结构体eventResp定义 2.6.5
detail结构体detailResp定义 2.6.6

2.6.5 eventResp 结构体定义

名称数据类型描述
datasource_idstring数据源id
idstring行为id
namestring行为名称
datestring发生的时间戳,单位到 毫秒
propertiesstring行为上报时用户的属性值,json 序列化后的string。如果请求参数中need_properties等于false,则此字段为空

2.6.6 detailResp 结构体定义

名称数据类型描述
datasource_idstring数据源id
idstring明细id
namestring明细名称
valuestring明细具体的值
datestring发生的时间戳,单位到 毫秒

2.7 获取所有在线可用的标签/属性/明细/行为事件 列表

对应查询如下前端页面展示的开启了在线导入且导入成功过的对应数据

基本信息

生效版本1.18
功能描述按租户获取在线可用的标签/属性/明细/行为列表,在sass环境,租户和集团关联,会自动按租户绑定的集团过滤
接口模块LabelApi
接口名称GetOnlineTagsProp
请求类型GET

请求参数

  • Query参数
名称数据类型是否必选描述
ApiActionString对应“基本信息”中的“接口名称”
ApiVersionString版本号: 2023-06-20
tenantCodeString租户Code (请不要填写租户ID,获取方式详见附录)

infoType

String

选择需要查询标签(label)还是属性(property),行为(behavior)明细(detail),取值是:label,property,behavior,detail

idTypeInt标签的idtype ,传每个主体下面的base id 的id。
currentint当前页
pageSizeint分页大小
  • Header(按照网关要求,无特殊要求)
名称数据类型是否必选描述
AuthorizationString见《开发前必读》3.3中提到的签名
  • Body(无)

响应参数

名称数据类型描述

id

Int

对应标签/属性/行为/明细资源的id

nameString对应资源的名称
statusString在线资源状态,此接口只会返回succeed的资源
LatestSuccessDateString最新可用的日期
dataSourceIdInt资源对应的数据源id

返回示例:

{
    "data": {
        "items": [
            {
                "id": 2,
                "name": "autotest0131/autotest_guize01311730",
                "status": "succeed",
                "LatestSuccessDate": "2023-02-12" ,//最新可用的日期
                "dataSourceId":1
            }
        ],
        "page": 1,
        "pageSize": 20,
        "total": 1
    },
    "code": 0
}

注意