查询 API

最后更新于：2018-08-06 11:06:48

本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。

查询 API 主要用于获取各种数据分析报告。

1. 调用方法

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

2. 通用参数

2.1 属性表达式

几乎所有的 API 都会用到属性表达式，例如按照某个属性进行过滤、分组或者聚合等等。属性包括事件属性和用户属性，事件属性使用 event.事件名.属性名 的方式，例如表示 注册渠道 这个属性的表达式如下:

  event.Signup.Channel

用户属性类似，例如表示 用户性别:

  user.Gender

2.2 筛选表达式

筛选表达式同样适用于绝大多数 API，用于表示对某些事件或者用户的筛选操作，使用如下格式的 JSON 表示:

{
  // 表示 conditions 里的各个条件的关系是 或 还是 且 
  "relation": "and",
  // 具体的条件列表，可以有多个
  "conditions": [{
    // 条件的左值，是一个属性表达式
    "field": "event.BuyGold.$os",
    // 条件的操作符，这里表示等于
    "function": "equal",
    // 条件的参数，根据不同的操作符可以有一个或者多个
    "params": [
      "iOS"
    ]
  }, {
    "field": "user.Gender",
    "function": "equal",
    "params": [
      "男"
    ]
  }]
}

目前支持的操作符如下:

  • equal / notEqual

    表示等于/不等于，对字符串、数值类型有效。如果 Params 有多个，则相当于 In 或者 Not In。例如想筛选出来自北京或者上海的用户:

    {
  "field": "user.$city",
  "function": "equal",
  "params": ["北京", "上海"]
}

  • isTrue / isFalse

    只对布尔类型有效。

  • isSet / notSet

    某个属性是否有值，对字符串、数值类型有效。

  • include

    针对集合的操作，表示包含某个元素，例如筛选出所有喜欢苹果的用户:

    {
  "field": "user.FavoriteFruits",
  "function": "include",
  "params": ["Apple"]
}

  • less / greater / between：表示小于/大于/小于且大于，其中 between 是前闭后闭的区间，只对数值类型有效。例如筛选买入黄金的价格在 230 和 232 之间的所有事件:

    {
  "field": "event.BuyGold.GoldPrice",
  "function": "between",
  "params": [230, 232]
}

  • contain / notContain

    包含或者不包含，表示字符串的部分匹配，只对字符串类型有效。

  • absoluteBetween / relativeBefore / relativeWithin

    针对日期类型的操作符，分别表示在一个绝对日期范围/在 N 天之前/在 N 天之内。例如想筛选所有注册时间在 3 天之内的用户:

    {
  "field": "user.$signup_time",
  "function": "relativeWithin",
  "params": [3]
}

    或者筛选所有在 2015-1-1~2015-1-10 注册的用户:

    {
  "field": "user.$signup_time",
  "function": "absoluteBetween",
  "params": ["2015-01-01", "2015-01-10"]
}

3. 行为分析报告

所有的分析报告均有 JSON 和 CSV 两种格式，默认是 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析报告对应的 CSV 格式的 URL 为: /events/report?format=csv 。

3.1 事件分析报告

[POST /events/report]

  • Request (application/json)
  • Response 200 (application/json)
  • 使用 curl 示例

关键参数说明：

  • aggregator: 聚合操作符，可取值为：
    • count: 时间触发次数
    • uniq_count:触发用户数
    • uniq_avg:人均次数或人均值
    • sum: 数值总和
    • max:数值最大值
    • min:数值最小值
    • avg:数值平均值
  • field: 若aggregator为sum/max/min/avg，需要添加field字段，即聚合的字段名，与aggregator同级，例如：“field" : "event.payOrder.discountAmount"
  • bucket_params: 分桶条件，对数值型属性进行分组时，可以自定义分桶条件，分桶条件里所包含的属性必须全包含在分组属性“by_fields”
  • limit: 最大分组个数，如果limit较大（超过1W），建议使用stream模式下载（仅对于事件分析）。stream模式开启：添加参数“downloadOriginalFormat”：true

3.2 漏斗分析报告

[POST /funnels/report]

  • Request (application/json)
  • Response 200 (application/json)
  • 使用 curl 示例

3.3 留存分析报告

[POST /retentions/report]

  • Request (application/json)
  • Response 200 (application/json)
  • 使用 curl 示例

3.4 分布分析报告

[POST /addictions/report]

  • Request (application/json)
  • Response 200 (application/json)
  • 使用 curl 示例

3.5 用户路径分析报告

[POST /path/analytics/report]

  • Request (application/json)
  • Response 200 (application/json)
  • 使用 curl 示例

3.6 属性分析报告

[POST /user/analytics/report]

  • Request (application/json)
  • Response 200 (application/json)
  • 使用 curl 示例

4. 用户明细查询

用户明细系列接口用于查询某一个特定分析报告中的具体用户列表，请求的大部分参数与分析报告相同，新增的参数会在每个接口里具体说明。用户列表也支持 JSON 和 CSV 两种格式，默认式 JSON 格式，如果需要 CSV 格式的数据可以手动指定 format 参数。例如事件分析的用户列表对应的 CSV 格式的 URL 为: /events/user/list?format=csv。

4.1 事件分析用户明细报告

[POST /events/user/list]

  • Request (application/json)
  • Response 200 (application/json)

4.2 漏斗分析用户明细报告

[POST /funnels/user/list]

  • Request (application/json)
  • Response 200 (application/json)

4.3 留存分析用户明细报告

[POST /retentions/user/list]

  • Request (application/json)
  • Response 200 (application/json)

4.4 分布分析用户明细报告

[POST /addictions/user/list]

  • Request (application/json)
  • Response 200 (application/json)

4.5 用户分群/属性分析用户明细报告

[POST /users/list]

  • Request (application/json)
  • Response 200 (application/json)

这个接口也可以指定要查询的用户id，这样能获取指定用户的属性信息。

  • Request (application/json)
  • Response 200 (application/json)

4.6 用户路径用户明细报告

[POST /users/list]

  • Request (application/json)
  • Response 200 (application/json)

5. 自定义查询和用户行为列表

5.1 自定义查询

[GET /sql/query]

通过 SQL 进行自定义查询，详见自定义查询功能的介绍。

  • Parameters

    • q: 查询的 SQL，例如 SELECT event,time,user_id FROM events LIMIT 10。
    • format: 可能的值包括
      • csv：默认格式
      • json：每行一个 JSON
      • event_json：导出可以用于直接导入的 Event Track 格式的 Json（1.*.3338 之后的版本支持）
      • profile_json：导出可以用于直接导入的 Profile Set/Track Signup 格式的 Json（1.*.3338 之后的版本支持）
      • sql：不直接返回数据，而是翻译为一条可以直接在 Spark/Impala/Hive 里执行的 SQL

  • Response 200 (text/plain)

该接口和其它 API 的调用方式有所不同，q 参数直接用 GET/POST 参数传递即可，返回的数据为 \t 分隔。一个使用 curl 的例子如下:

curl 'https://saasdemo.cloud.sensorsdata.cn/api/sql/query?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default' \
-X POST \
--data-urlencode "q=SELECT * FROM events LIMIT 10" \
--data-urlencode "format=csv"

5.2 用户行为列表

[POST /users/event/list]

获取一个或者多个用户在某一段时间内的详细行为信息。

  • Request (application/json)
  • Response 200 (application/json)