分群查询

1. 分群的用户明细查询

获取某个分群下的用户明细。

更新记录:4.3.4版本新增,4.6版本中增加分页功能

适合单批次获取小量级数据量(根据内存限定,一般为1万),如果需要获取或者导出更多,在5.0版本中,可选用 分群的用户用户明细导出

1.1 接口地址

【POST】 /uba/api/cohort/users

1.2 请求参数示例

4.3.4版本
4.6版本
4.3.4版本

获取单个分群的用户属性数据

{
// 【必填】分群code
"cohortCode":"arkfq_3",
//需要获取的用户条数
"limit":2,
//【选填】指定需要查询的用户属性列,传用户属性ID
"properties":["xwho", "distinct_id", "$imei", "$first_visit_language", "$signup_time"]
}

limit:获取用户分群下的用户条数,默认为1000。

properties:指定需要的用户属性列,传入用户属性ID,可以通过方舟系统或者 元数据管理-用户属性 接口获取用户属性列表。不指定默认查询方舟系统【元数据管理 - 用户属性】中 可见 的所有用户属性。

认证参数:接口必传token和appKey两个参数,详情见 项目接口认证

4.6版本

增加page和pageSize两个参数,用来支持分页查询。

{
// 【必填】分群code
"cohortCode":"arkfq_3",
//需要获取的用户条数
"limit":2,
//【选填】指定需要查询的用户属性列,传用户属性ID
"properties":["xwho", "distinct_id", "$imei", "$first_visit_language", "$signup_time"],
//【选填】当前页,从1开始,不需要分页不用传值
"page":1
//【选填】每页大小,和page配合使用,值不能大于limit
"pageSize":1000
}

limit:获取用户分群下的用户条数,无分页参数时默认为1000。有分页时默认为分群用户数,如果指定limit值会影响总页数和最终返回的结果集。

properties:指定需要的用户属性列,传入用户属性ID,可以通过方舟系统或者 元数据管理-用户属性 接口获取用户属性列表。不指定默认查询方舟系统【元数据管理 - 用户属性】中 可见 的所有用户属性。

page:当前页数。page为空表示不分页,page有值时取指定页结果,页数从1开始。

pageSize:每页条数。page有值时,pageSize不能为空,且值不能大于limit。

认证参数:接口必传token和appKey两个参数,详情见 项目接口认证

1.3 返回结果示例

{
//分群下总用户条数
"count":46,
//【4.6中新增】当前页
"page": 1,
//结果返回的用户条数
"size":2,
//用户详情
"users":[
{
"$imei":null,
"$first_visit_language":"zh-cn",
"distinct_id":4255875062385414000,
"$signup_time":null,
"xwho":"JSd650856937040a530ff54fdaab4e56d7d650"
},
{
"$imei":null,
"$first_visit_language":"zh-cn",
"distinct_id":-4635244755532264000,
"$signup_time":null,
"xwho":"JS1c6d11e3e67bf0dc02030d3fd393310b1c6d"
}
]
}

1.4 接口调用示例

curl -H "Content-Type:application/json" -H "token:4113c9cad1c301113783f433e254888c" -H "appKey:31abd9593e9983ec" -X POST --data '{
"cohortCode":"arkfq_3",
"limit":2,
"properties":["xwho", "distinct_id", "$imei", "$first_visit_language", "$signup_time"]
}' http://127.0.0.1:4005/uba/api/cohort/users

2. 分群的用户明细导出

5.0版本中新增

适用于需要一次性导出或者获取更多(百万级以下)的分群用户明细数据的场景,返回接口使用的是流式输出。

2.1 接口地址

【POST】 /uba/api/cohort/users/export

2.2 请求参数

{
// 【必填】分群code
"cohortCode":"arkfq_3",
//需要获取的用户条数,不传指获取全部
"limit":10000,
//【选填】指定需要查询的用户属性列,传用户属性ID
"properties":["xwho", "distinct_id", "$imei", "$first_visit_language", "$signup_time"],
}

limit:获取用户分群下的用户条数,可传可不传,不传为全部

properties:指定需要的用户属性列,传入用户属性ID,可以通过方舟系统或者 元数据管理-用户属性 接口获取用户属性列表。不指定默认查询方舟系统【元数据管理 - 用户属性】中 可见 的所有用户属性。

认证参数:接口必传token和appKey两个参数,详情见 项目接口认证

2.3 返回结果示例

{"$city":"BJ","$email":"(已脱敏)","$platform":"JS","xwho":"JSa0438f992d07a31d9f079ca479cd4796a043"}
{"$city":"CS","$email":"(已脱敏)","$platform":"JS","xwho":"JS01cb9f5096f452a10b03e90b0694dee401cb"}
{"$city":"SH","$email":"(已脱敏)","$platform":"JS","xwho":"JS9e931e93f9674491b77eba3103e638cf9e93"}
{"$city":"SZ","$email":"(已脱敏)","$platform":"JS","xwho":"JS7b4dc11ab426603295ab11811d69797a7b4d"}
{"$city":null,"$email":"(已脱敏)","$platform":"JS","xwho":"JS72889204a97a39e06a220c1aa3b4fdbd7288"}
{"$city":"GZ","$email":"(已脱敏)","$platform":"JS","xwho":"JS9a99fc0dcebf31b7a75f349cac6cd2c09a99"}
  1. 行为序列导出 接口输出,因为可以支撑大数据量,为了方便客户端可以进行批次处理,json类型的输出并非是一个完整的json数组,而是一行一条json(无[],按\n分割)

  2. 行为序列导出接口输出,因为可以支撑大数据量,接口response为 流式输出。如果是通过程序来调用,那么建议:

    • 建议一:避免一次性加载response到内存中,改为流式接收 response body

    • 建议二:Http Connection 需要增加SocketTimeout时长,同时修改Nginx 超时配置

2.4 接口调用示例

导出人群为arkfq_98的所有用户,输出写入到output.json 文件中

curl -o output.json -H "Content-Type:application/json" -H "token:3edbaf427ecdda80beef322ad3c333a4" -H "appKey:31abd9593e9983ec" -X POST --data '{
"cohortCode":"arkfq_98",
"properties":["xwho","$email","$platform","$city"]
}' https://127.0.0.1:4005/uba/api/cohort/users/export

关于流式导出类型API的java 客户端调用示例可以参考 【API-自定义查询-Java HttpClient 接口调用示例