# 用户分群和标签 API

调用方法请参见Open API文档中的调用方法描述。

# 一、通用参数字段说明

字段 描述
projectId 102
clusterName 分群名称
displayName 分群显示名称
clusterCatalog 分群类别
clusterType 分群类型
qp 分群查询条件（类型为 UserClusterDef）
tagQp 标签查询条件

分群类别（clusterCatalog）取值说明:

值 描述
catalog_cluster 分群
catalog_tag 标签

分群方式（clusterType）取值说明:

值 描述
cluster_by_dynamic_condition 动态条件更新用户群
cluster_by_static_condition 静态条件用户群
cluster_by_result 结果分群
cluster_by_import 自定义上传 ID 分群
tag_by_dynamic_condition 动态条件更新用户标签
tag_by_static_condition 静态条件用户标签
tag_by_import 自定义上传 ID 标签

UserClusterDef 字段说明：

字段 描述
events 参与事件条件列表
event_relation 参与事件条件之间的逻辑关系
filts 用户属性条件列表
relation 用户属性条件之间的逻辑关系
event_user_relation 参与事件条件列表与用户属性条件列表之间的逻辑关系

# 二、添加条件分群，结果分群或用户标签

[POST /open/user-cluster-add?token=xxxxxxx]

  • 条件分群 Request body (application/json)
{
  "projectId": 102,
  "clusterName": "recent_7_days_consume",
  "clusterCatalog": "catalog_cluster",
  "clusterType": "cluster_by_static_condition",
  "displayName": "recent_7_days_consume",
  "qp": {
    "events": [
      {
        "comparator": "greater",
        "endTime": "2020-01-09 00:00:00",
        "eventName": "consume_item",
        "num": "4",
        "recentDay": "1-7",
        "startTime": "2020-01-03 00:00:00",
        "taPropQuota": {
          "analysis": "TIMES"
        }
      }
    ],
    "event_relation": "and",
    "filts": [
      {
        "columnName": "user_level",
        "comparator": "equal",
        "ftv": [
          "3"
        ],
        "tableType": "user"
      }
    ],
    "relation": "and",
    "event_user_relation": "and"
  }
}
  • 条件标签 Request body (application/json)
{
  "projectId": 102,
  "clusterName": "tag_20200615_1",
  "clusterCatalog": "catalog_tag",
  "clusterType": "tag_by_static_condition",
  "displayName": "标签_20200615_1",
  "tagQp": {
    "userTagValueDefs": [
      {
        "tagRemark": "",
        "tagValue": "标签值1",
        "userClusterDef": {
          "event_relation": "and",
          "event_user_relation": "and",
          "events": [
            {
              "endTime": "2020-06-14 17:36:40",
              "eventName": "player_register",
              "num": "4",
              "recentDay": "1-30",
              "relation": "and",
              "startTime": "2020-05-16 17:36:40",
              "taPropQuota": {
                "analysis": "TIMES"
              },
              "comparator": "greater"
            }
          ],
          "filts": [],
          "relation": "and"
        }
      },
      {
        "tagRemark": "",
        "tagValue": "标签值2",
        "userClusterDef": {
          "event_relation": "and",
          "event_user_relation": "and",
          "events": [
            {
              "endTime": "2020-06-14 17:36:55",
              "eventName": "fight_success",
              "num": "0",
              "recentDay": "1-30",
              "relation": "and",
              "startTime": "2020-05-16 17:36:55",
              "taPropQuota": {
                "analysis": "TIMES"
              }
              "uceCalcuSymbol": "greater"
            }
          ],
          "filts": [],
          "relation": "and"
        }
      }
    ]
  }
}

tagQp 字段说明：

字段 描述
tagValue 标签值
userClusterDef 标签值匹配定义，字段定义见 UserClusterDef
  • Response body (application/json)
{
  "return_code": 0,
  "return_message": "success",
  "data": 970
}

结果字段说明：

字段 描述
data 分群 id

# 三、分群或标签详情查询

通过 clusterId 或者 clusterName 查询详情

[GET /open/user-cluster-detail?token=xxxxxxx&projectId=xxx&clusterId=xxxxxx]

[GET /open/user-cluster-detail?token=xxxxxxx&projectId=xxx&clusterName=xxxxxx]

  • Response body (application/json)
{
  "data": {
    "clusterName": "recent_7_days_consume",
    "clusterType": "cluster_by_static_condition",
    "displayName": "recent_7_days_consume",
    "id": 970,
    "progress": 1,
    "projectId": 102,
    "refreshTime": "2020-01-10 10:51:14",
    "userClusterDef": {
      "event_relation": "and",
      "event_user_relation": "and",
      "events": [
        {
          "comparator": "greater",
          "endTime": "2020-01-09 00:00:00",
          "eventName": "consume_item",
          "num": "4",
          "recentDay": "1-7",
          "startTime": "2020-01-03 00:00:00",
          "taPropQuota": {
            "analysis": "TIMES"
          }
        }
      ],
      "filts": [
        {
          "columnName": "user_level",
          "comparator": "equal",
          "ftv": [
            "3"
          ],
          "tableType": "user"
        }
      ],
      "relation": "and"
    },
    "userId": 13,
    "usersNum": 0
  },
  "return_code": 0,
  "return_message": "success"
}

参数字段说明请参考通用参数字段说明

# 四、更新分群和标签

[POST /open/user-cluster-update?token=xxxxxxx&clusterId=xxx]

  • Request body (application/json)
{
  "clusterCatalog": "catalog_cluster",
  "clusterType": "cluster_by_static_condition",
  "displayName": "recent_7_days_consume",
  "projectId": 102,
  "qp": {
    "event_relation": "and",
    "event_user_relation": "and",
    "events": [
      {
        "comparator": "greater",
        "endTime": "2020-01-09 00:00:00",
        "eventName": "consume_item",
        "num": "4",
        "recentDay": "1-7",
        "startTime": "2020-01-03 00:00:00",
        "taPropQuota": {
          "analysis": "TIMES"
        }
      }
    ],
    "filts": [
      {
        "columnName": "user_level",
        "comparator": "equal",
        "ftv": [
          "3"
        ],
        "tableType": "user"
      }
    ],
    "relation": "and"
  }
}

参数字段说明请参考通用参数字段说明

  • Response body (application/json)
{
  "return_code": 0,
  "return_message": "success"
}

# 五、删除分群或标签

[POST /open/user-cluster-delete?token=xxxxxxx&projectId=xxx&clusterId=xxxxxx]

  • Response body (application/json)
{
  "return_code": 0,
  "return_message": "success"
}

# 六、分群和标签列表查询

[POST /open/user-cluster-list?token=xxxxxxx]

  • Request body (application/json)
{
  "clusterCatalog": "catalog_cluster",
  "clusterTypes": [
    "cluster_by_dynamic_condition",
    "cluster_by_static_condition"
  ],
  "pagerHeader": {
    "pageNum": 1,
    "pageSize": 10
  },
  "projectId": 102
}
  • Response body (application/json)
{
  "data": {
    "pagerResult": {
      "pageNum": 1,
      "pageSize": 10,
      "totalNum": 2
    },
    "userClusters": [
      {
        "clusterName": "xuzz_ces",
        "clusterType": "cluster_by_static_condition",
        "displayName": "用户数",
        "id": 905,
        "progress": 100,
        "refreshTime": "2019-11-01 15:08:31",
        "remarks": "2134",
        "userId": 108,
        "userName": "xuzz",
        "usersNum": 4665
      },
      {
        "clusterName": "test",
        "clusterType": "cluster_by_static_condition",
        "displayName": "test",
        "id": 183,
        "progress": 100,
        "refreshTime": "2019-11-01 15:05:28",
        "remarks": "test",
        "userId": 108,
        "userName": "xuzz",
        "usersNum": 5603
      }
    ]
  },
  "return_code": 0,
  "return_message": "success"
}

# 七、刷新条件分群或标签并获取进度

[POST /open/user-cluster-refresh?token=xxxxxxx&projectId=xxx&clusterId=xxxxxx]

  • Response body (application/json)
{
  "return_code": 0,
  "return_message": "success"
}

提交刷新后，可查询刷新进度

[GET /open/user-cluster-refresh-progress?token=xxxxxxx&projectId=xxx&clusterId=xxxxxx]

  • Response body (application/json)
{
  "data": {
    "progress": 80,
  },
  "return_code": 0,
  "return_message": "success"
}

结果字段说明：

字段 描述
progress 取值范围[0, 100], 100 代表刷新完成

# 八、创建上传 ID 分群

[POST /open/import-id-cluster-add?token=xxxxxxx&projectId=xxx&clusterName=xxxxxx&displayName=xxxx&remarks=xxxxx&mainColumnName=xxxxxx]

  • 参数说明
字段 是否选填 描述
displayName 必填 分群显示名称（最长 50 个字符）
mainColumnName 必填 ID 分群关联属性
clusterName 选填 分群名称（最长 24 个字符） ，字母数字构成，不填则由系统生成
remarks 选填 分群备注

HTTP 请求头 Content-Type 为 text/csv, 请求体为 csv 文件的内容。

  • curl 示例(trace.txt 删除 Send/Recv 描述行)
[root@ta1 ~]# curl --trace-ascii trace.txt --header 'Content-Type: text/csv' --data-binary '@test.csv' 'http://ta2:8992/open/import-id-cluster-add?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&projectId=102&displayName=xxxx&mainColumnName=%23account_id'
{"data":{"clusterId":1889,"successNum":5,"tagValueNullNum":0,"unmatchedNum":0,"uploadNum":5,"userNum":5},"return_code":0,"return_message":"success"}
[root@ta1 ~]#
[root@ta1 ~]#
[root@ta1 ~]# cat trace.txt
== Info: About to connect() to ta2 port 8992 (#0)
== Info:   Trying 10.81.129.35...
== Info: Connected to ta2 (10.81.129.35) port 8992 (#0)
0000: POST /open/import-id-cluster-add?token=bTOzKiTIozG4e19FgXphcA8dD
0040: V3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&projectId=102&displayNam
0080: e=xxxx&mainColumnName=%23account_id HTTP/1.1
00ae: User-Agent: curl/7.29.0
00c7: Host: ta2:8992
00d7: Accept: */*
00e4: Content-Type: text/csv
00fc: Content-Length: 43
0110:
0000: j77639
0008: h84497
0010: g119426
0019: e154284
0022: f175355
== Info: upload completely sent off: 43 out of 43 bytes
0000: HTTP/1.1 200 OK
0000: Date: Thu, 05 Nov 2020 04:06:31 GMT
0000: Content-Type: application/json;charset=utf-8
0000: Content-Length: 148
0000:
0000: {"data":{"clusterId":1889,"successNum":5,"tagValueNullNum":0,"un
0040: matchedNum":0,"uploadNum":5,"userNum":5},"return_code":0,"return
0080: _message":"success"}
== Info: Connection #0 to host ta2 left intact

# 九、修改上传 ID 分群

[POST /open/import-id-cluster-modify?token=xxxxxxx&projectId=xxx&clusterId=xxxxxx&displayName=xxxx&remarks=xxxxx&mainColumnName=xxxxxx]

  • 参数说明
字段 是否选填 描述
clusterId 必填 分群 ID
displayName 选填 分群显示名称（最长 50 个字符）
mainColumnName 选填 ID 分群关联属性
remarks 选填 分群备注

HTTP 请求头 Content-Type 为 text/csv, 请求体为 csv 文件的内容。

  • curl 示例(trace.txt 删除 Send/Recv 描述行)
[root@ta1 ~]# curl --trace-ascii trace.txt --header 'Content-Type: text/csv' --data-binary '@test.csv' 'http://ta2:8992/open/import-id-cluster-modify?token=bTOzKiTIozG4e19FgXphcA8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&projectId=102&clusterId=1889&displayName=xxxx&mainColumnName=%23account_id'
{"data":{"clusterId":1889,"successNum":5,"tagValueNullNum":0,"unmatchedNum":0,"uploadNum":5,"userNum":5},"return_code":0,"return_message":"success"}
[root@ta1 ~]#
[root@ta1 ~]#
[root@ta1 ~]# cat trace.txt
== Info: About to connect() to ta2 port 8992 (#0)
== Info:   Trying 10.81.129.35...
== Info: Connected to ta2 (10.81.129.35) port 8992 (#0)
0000: POST /open/import-id-cluster-modify?token=bTOzKiTIozG4e19FgXphcA
0040: 8dDV3DIY8RwdHTO7aSnBsRqSNaIk19BnBMecJDWibD&projectId=102&cluster
0080: Id=1889&displayName=xxxx&mainColumnName=%23account_id HTTP/1.1
00c0: User-Agent: curl/7.29.0
00d9: Host: ta2:8992
00e9: Accept: */*
00f6: Content-Type: text/csv
010e: Content-Length: 43
0122:
0000: j77639
0008: h84497
0010: g119426
0019: e154284
0022: f175355
== Info: upload completely sent off: 43 out of 43 bytes
0000: HTTP/1.1 200 OK
0000: Date: Thu, 05 Nov 2020 04:12:58 GMT
0000: Content-Type: application/json;charset=utf-8
0000: Content-Length: 148
0000:
0000: {"data":{"clusterId":1889,"successNum":5,"tagValueNullNum":0,"un
0040: matchedNum":0,"uploadNum":5,"userNum":5},"return_code":0,"return
0080: _message":"success"}
== Info: Connection #0 to host ta2 left intact

← 维度表 API →