# 用户分群和标签 API

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

# 一、通用参数字段说明

字段	描述
projectId	项目ID
clusterName	分群名(分群号)
displayName	分群显示名
clusterCatalog	分群类别
clusterType	分群类型
qp	分群定义
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 标签

# 二、添加条件分群或标签

# 添加条件分群

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

qp 字段说明：

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

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",
        "eventName": "consume_item",
        "num": "4",
        "recentDay": "1-7",
        "taPropQuota": {
          "analysis": "TIMES"
        }
      }
    ],
    "event_relation": "and",
    "filts": [
      {
        "columnName": "user_level",
        "comparator": "equal",
        "ftv": [
          "3"
        ],
        "tableType": "user"
      }
    ],
    "relation": "and",
    "event_user_relation": "and"
  }
}

# 添加条件标签

subConditionTabType 字段说明：

字段	描述
tag_condition_default	自定义条件标签
tag_condition_by_firstlast_event	首末次特征标签

tagQp 字段包含了标签定义，不同类型标签使用不同的字段：

字段	描述
userTagValueDefs	自定义条件标签
userTagConFirstLastEventDef	首末次特征标签

# 自定义条件标签

userTagValueDefs 字段说明：

字段	描述
tagValue	标签值
userClusterDef	标签值匹配定义，字段定义见 UserClusterDef

Request body (application/json)

{
  "projectId": 102,
  "clusterName": "tag_20200615_1",
  "clusterCatalog": "catalog_tag",
  "clusterType": "tag_by_static_condition",
  "subConditionTabType" : "tag_condition_default",
  "displayName": "标签_20200615_1",
  "tagQp": {
    "userTagValueDefs": [
      {
        "tagRemark": "",
        "tagValue": "标签值1",
        "userClusterDef": {
          "event_relation": "and",
          "event_user_relation": "and",
          "events": [
            {
              "eventName": "player_register",
              "num": "4",
              "recentDay": "1-30",
              "relation": "and",
              "taPropQuota": {
                "analysis": "TIMES"
              },
              "comparator": "greater"
            }
          ],
          "filts": [],
          "relation": "and"
        }
      },
      {
        "tagRemark": "",
        "tagValue": "标签值2",
        "userClusterDef": {
          "event_relation": "and",
          "event_user_relation": "and",
          "events": [
            {
              "eventName": "fight_success",
              "num": "0",
              "recentDay": "1-30",
              "relation": "and",
              "taPropQuota": {
                "analysis": "TIMES"
              }
              "uceCalcuSymbol": "greater"
            }
          ],
          "filts": [],
          "relation": "and"
        }
      }
    ]
  }
}

# 首末次特征标签

Request body (application/json)

{
  "projectId": 2,
  "clusterName": "tag_test_20200615_1",
  "clusterCatalog": "catalog_tag",
  "clusterType": "tag_by_static_condition",
  "subConditionTabType": "tag_condition_by_firstlast_event",
  "displayName": "标签_test",
  "tagQp": {
    "userTagConFirstLastEventDef": {
      "userTagConFirstLastEvent": {
        "calcPropVo": {
          "isCalc": false,
          "property": {
            "columnName": "#vp@test_num",
            "tableType": "event"
          }
        },
        "eventName": "pay",
        "isFirstEvent": true,
        "recentDay": "0-1",
        "filts": [
          {
            "columnName": "#os",
            "comparator": "equal",
            "ftv": [
              "android"
            ],
            "tableType": "event"
          }
        ],
        "relation": "and"
      }
    }
  }
}

# 指标值标签 (从版本 3.2.1 开始支持)

Request body (application/json)

{
  "projectId": 2,
  "clusterName": "tag_test_20200615_1",
  "clusterCatalog": "catalog_tag",
  "clusterType": "tag_by_static_condition",
  "subConditionTabType": "tag_condition_by_quotation",
  "displayName": "标签_test",
  "tagQp": {
    "userTagConQuotaDef": {
      "userTagConQuotaEvent": {
        "type": "normal",
        "quota": "activity_reward",
        "analysis": "DISTINCT",
        "eventName": "activity_attend",
        "recentDay": "0-1",
        "filts": [
          {
            "columnName": "#os",
            "comparator": "equal",
            "ftv": [
              "android"
            ],
            "tableType": "event"
          }
        ],
        "relation": "and"
      }
    }
  }
}

# 结果说明

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"
}

结果字段	描述
userClusterDef	分群定义，同qp
userTagDef	标签定义，同tagQp

# 四、更新条件分群或标签定义

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

[POST /open/user-cluster-update-by-name?token=xxxxxxx&projectId=xxx&clusterName=xxxxx]

更新定义的参数和添加的参数一致

# 更新条件分群定义

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"
  }
}

# 五、删除分群或标签

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

[POST /open/delete-user-cluster-by-name?token=xxxxxxx&projectId=xxx&clusterName=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]

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

Response body (application/json)

{
  "return_code": 0,
  "return_message": "success"
}

# 查询刷新进度

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

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

[GET /open/user-cluster-refresh-progress-by-name?token=xxxxxxx&projectId=xxx&clusterName=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	必填	分群关联属性
clusterCatalog	选填	分群类别: catalog_cluster, catalog_tag。默认为catalog_cluster
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,"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,"tagValueNullNum":0,"unmatchedNum":0,"
0040: uploadNum":5,"userNum":5},"return_code":0,"return_message":"succ
0080: ess"}
== 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]

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

参数说明

字段	是否选填	描述
clusterId	必填	分群ID
clusterName	必填	分群名
displayName	选填	分群显示名（最长 50 个字符）
mainColumnName	选填	分群关联属性
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,"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,"tagValueNullNum":0,"unmatchedNum":0,"
0040: uploadNum":5,"userNum":5},"return_code":0,"return_message":"succ
0080: ess"}
== Info: Connection #0 to host ta2 left intact

← 数据自定义查询 API 维度表 API →