查询 API

最后更新于:2019-07-31 12:34:49

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

查询 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 参数传递即可,csv 格式返回的数据为 \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)