分群查询

1. 分群的用户明细查询

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

更新记录：4.3.4版本新增，4.6版本中增加分页功能

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

1.1 接口地址

【POST】 /uba/api/cohort/users

1.2 请求参数示例

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两个参数，详情见 项目接口认证。

5.2版本

5.2可支持获取用户的标签属性

{
    // 【必填】分群code
    "cohortCode":"arkfq_3",
    //需要获取的用户条数
    "limit":2,
    //【选填】指定需要查询的用户属性列，传用户属性ID
    "properties":["xwho", "distinct_id", "$imei", "$first_visit_language", "$signup_time"],
  	//【4.6中新增】【选填】当前页，从1开始，不需要分页则不用传值
  	"page":1
    //【4.6中新增】【选填】每页大小，和page配合使用，值不能大于limit
  	"pageSize"：1000，
    //【选填】5.2版本新增，要获取的标签code，如果不指定则不获取任何标签内容
  	"tags":[
      	//标签参数包含code和version两个部分，version可以不指定，不指定时默认获取最新标签
        {"code":"tag_3"},
        {"code":"tag_4"},
        {"code":"tag_6"}
    ]
}

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",
            //tag.开头的为标签数据，指定标签code才会查询
            "tag.tag_3":"高消费"
        }
    ]
}

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 接口调用示例】