通用的API查询参数说明

通用API查询参数

七大模型从页面操作上来，有一些通用的请求Body参数，例如"全局筛选"、“分组项”、“分析主体“以及具体的计算时间及粒度，故我们将这些参数的做单独说明，每个模型特有的参数将在各个分析API中展示

如何表示一个属性

在API查询中，您会发现很多地方会用到事件/用户属性参数，那在DataTower中，我们使用可以用一个对象来准确表示一个事件或用户属性

参数说明

示例

  {
      "id":1213
      "table_type": 0,
      "name": "#acid",
      "display_name": "账号 ID",
      "type": 1,
      "data_type": "string",
 }

如何表示一个筛选条件

在API查询中，当需要使用筛选条件时（如全局筛选或者针对单个事件的筛选），我们可以使用一个对象结构来表示筛选条件参数，DataTower支持两层嵌套筛选条件的数据结构

每一个筛选项，由两到三部分构成：属性 + 筛选符号 + 具体筛选值（可选），然后不同筛选项之间可以是"且"、"或"的关系构成一个大筛选，而大筛选之间也可以是"且"和"或"的关系。

以下图为例我们有三个筛选项，分别是：

• 账号ID（属性） + 等于 （筛选符号） + "abc1234"（具体筛选值）
• 应用版本号（属性）+ 有值（筛选符号）
• 安装时间（属性） + 位于区间（筛选符号）+ "2024-12-23 00:00:00 - 2024-12-23 23:59:59"（具体筛选值）

整个筛选条件为"安装时间位于2024-12-23 00:00:00到2024-12-23 23:59:59，或者是账号ID等于abc1234同时应用版本号不为空"

参数说明

extra参数解释

由于对象属性以及维度属性等存在父属性等关联属性，所以需要extra参数标识，为其他属性时，extra可以保持为空对象即{}，使用过程中，有参数疑问时，请联系DT团队

当为维度属性时

当为子属性（包含对象子属性，对象组子属性，列表子属性等）时

示例

上图所示的筛选条件，最终的参数为：

 {
        "relation": "or",
        "filters": [
            {
                "filterType": "COMPOUND",
                "relation": "and",
                "filters": [
                    {
                        "type": 1,
                        "columnName": "#acid",
                        "columnDesc": "账号ID",
                        "columnType": "string",
                        "comparator": "C00",
                        "filterValue": ["abc1234"],
                        "tableType": "event"
                    },
                    {
                        "type": 1,
                        "columnName": "#app_version_code",
                        "columnDesc": "应用版本号",
                        "columnType": "number",
                        "comparator": "C06",
                        "tableType": "event"
                    }
                ]
            },
            {
                "filterType": "SIMPLE",
                "relation": "and",
                "filters": [
                    {
                        "type": 1,
                        "columnName": "#app_install_time",
                        "columnDesc": "安装时间",
                        "columnType": "dateTime",
                        "comparator": "C08",
                        "filterValue": ["2024-12-23 00:00:00","2024-12-23 23:59:59"],
                        "tableType": "event"
                    }
                ]
            }
        ]
    }

如何表示一个分组项

在API查询中，当需要进行分组计算时，我们可以使用一个对象结构来表示参与分组的属性。对于一些特殊数据类型的，我们还可以支持分组的场景，如：

参数说明

extra参数解释

由于对象属性以及维度属性等存在父属性等关联属性，所以需要extra参数标识，为其他属性时，extra可以保持为空对象即{}，使用过程中，有参数疑问时，请联系DT团队

当为维度属性时

当为子属性（包含对象子属性，对象组子属性，列表子属性等）时

如何表示计算时间范围以及计算粒度

在分析模型中，往往需要指定计算的时间范围，以及时间计算的聚合粒度（按天、月、年），此时需要用到计算时间参数。DataTower支持静态时间和动态时间计算，其中静态时间指的是固定的一个时间点，例如2024-01-01，动态时间是基于计算时的时间进行动态偏移的时间点，例如7天前。

在计算时间参数中，我们使用recentDay和dateList来完整表示一个时间范围

{ 
  "dateList": [ "2023-12-27", "2024-01-02"] 
  "recentDay":""  // 必须为空字符串
}

{ "recentDay":"2024-12-05@@1"  // 表示2024-12-05到昨天 }

{"recentDay":"2$$4"  // 表示4天前到2天前 }

在某些计算时，还需要指定时间聚合的粒度，如事件分析中需要指明按天/周/月聚合，此时需要用到timeParticleSize字段

参数说明

示例

当我们想要计算时表示最近6天，按日聚合计算时，可用以下对象表示：

"eventsView":{
      "timeParticleSize":"day",
      "recentDay":"0$$6",
},

如何表示一个分析主体

在留存、漏斗、分布、间隔和路径分析中，我们需要指明所使用的分析主体，一般地，我们会使用预置的分析主体（$uid）。如果您想使用其他的分析主体，例如国家、设备号等等，可以先在项目配置中基于属性创建一个分析主体，然后在分析模型中使用。我们可以用如下对象表示分析主体，示例中可以看到，当您使用的是预置分析主体时，可以直接复制下面的例子：

    "entity": {
        "id": 155,
        "name": "用户ID",
        "entity_type": "PRIMARY",
        "column_desc": "DT 系统的用户唯一 ID；区分唯一事件流",
        "column_name": "$uid",
        "column_type": "varchar",
        "data_type": "string",
        "display_name": "DT 用户 ID",
        "table_type": "user",
        "type": 1
    },

特别注意： 以上参数与如何表示一个属性基本一致，但是table_type与如何表示一个属性存在出入，在分析主体中table_type为一个枚举，其中："event"：事件属性， "user"：用户属性，"cluster"：用户分群，"tag"：用户标签