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

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

神策分析提供一系列功能 API,利用这些 API 可以:

  1. 配置数据概览;
  2. 配置用户分群;
  3. 获取埋点统计报告;
  4. 获取某个用户的访问 TOKEN;

1. 调用方法

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

2. 数据概览

2.1. 增加数据概览

> [POST /dashboards]

+ Request (application/json)

{
 "name": "转化漏斗分析",
 "is_public": 0 // 0表示仅自己可见,1表示所有用户可见
} 

+ Response 200 (application/json)

{
"id": 2 // dashboard id 
}

2.2. 删除数据概览

> [DELETE /dashboards/{dashboardId}]

+ 使用 curl 示例

// $ID 为对应概览的 id,可由下面获取所有概览的 API 接口获取
curl 'https://golddemo.cloud.sensorsdata.cn/api/dashboards/$ID?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d&project=default'

2.3. 获取所有数据概览

> [GET /dashboards]

+ Response 200 (application/json)

[
  {
    "id": 1,
    "name": "营销数据分析",
    "create_time": "2015-11-04 16:34:33",
    "user_id": 1,
    "is_default": 0,
    "is_public": 1,
    "username": "admin",
    "project_id": 1,
    "config": "{\"widgetTime\":\"0 week\",\"widgetUnit\":\"minute\"}"
  },
  {
    "id": 3,
    "name": "产品黏性分析",
    "create_time": "2015-11-04 17:38:29",
    "user_id": 1,
    "is_default": 0,
    "is_public": 1,
    "username": "admin",
    "project_id": 1
  }
]


2.4. 获取某个数据概览的详情

>[GET /dashboards/{dashboardId}]

+ Response 200 (application/json)

{
  "id": 1, // 数据概览的id
  "name": "营销数据分析",  // 数据概览的名称
  "create_time": "2015-11-04 16:34:33", // 数据概览的创建时间
  "user_id": 1,
  "is_default": 0,
  "is_public": 1,
  "username": "admin",
  "items": [
    {
      "bookmark": {
        "id": 1,  // 书签id
        "type": "/segmentation/",
        "name": "每天不同渠道带来的用户量",
        "data": "{\"measures\":[{\"event_name\":\"views\",\"aggregator\":\"unique\"}],\"unit\":\"day\",\"by_fields\":[\"user.first_visit_channel\"],\"chartsType\":\"line\",\"sampling_factor\":64,\"from_date\":\"2016-06-20\",\"to_date\":\"2016-06-26\",\"bookmarkid\":\"1\",\"bookmarktime\":\"7 day\",\"rollup_date\":\"false\",\"filter\":{}}",
        "time": "7 day",
        "create_time": "2015-11-04 04:35:44",
        "user_id": 1,
        "dashboards": [],
        "related_events": [
          "views"
        ],
        "project_id": 1
      },
      "config": "{\"widgetIndex\":2,\"widgetByValues\":[\"百度\",\"36kr\",\"今日头条\"],\"widgetType\":\"column\",\"widgetTime\":\"7 day\",\"widgetUnit\":\"day\",\"widgetRememberType\":{\"unit\":\"column\"}}",
      "bookmark_id": 0
    },
    {
      "bookmark": {
        "id": 183,
        "type": "/segmentation/",
        "name": "每天不同渠道提交线索量",
        "data": "{\"measures\":[{\"event_name\":\"applies\",\"aggregator\":\"unique\"}],\"unit\":\"month\",\"by_fields\":[\"user.first_visit_channel\"],\"chartsType\":\"line\",\"sampling_factor\":64,\"from_date\":\"2016-01-01\",\"to_date\":\"2016-06-20\",\"filter\":{}}",
        "time": "7 day",
        "create_time": "2016-06-27 07:24:23",
        "user_id": 1,
        "dashboards": [],
        "related_events": [
          "applies"
        ],
        "project_id": 1
      },
      "config": "{\"widgetIndex\":3,\"widgetByValues\":[\"百度\",\"36kr\",\"今日头条\"],\"widgetType\":\"line\",\"widgetTime\":\"7 day\",\"widgetUnit\":\"day\",\"widgetRememberType\":{\"unit\":\"line\"}}",
      "bookmark_id": 0
    }
  ],
  "project_id": 1,
  "config": "{\"widgetTime\":\"0 week\",\"widgetUnit\":\"minute\"}"
}

2.5. 保存书签到数据概览

> [POST /bookmarks/bookmark]

保存书签到数据概览时,书签类型可以是事件分析,漏斗分析,留存分析,分布分析,对应的 type 分别是 /segmentation/, /funnel/, /retention/, /addiction/。data 是对应的 request,request 写法参考第三节。

+ Request (application/json)

{
  "related_events": [
    "Share"            
  ],
  "name": "分享的总次数",  // 书签名称
  "dashboards": [
    2            // 数据概览的id
  ],
  "type": "/segmentation/",  
  "data": "{\"measures\":[{\"event_name\":\"Share\",\"aggregator\":\"general\"}],\"unit\":\"day\",\"chartsType\":\"line\",\"sampling_factor\":64,\"rangeText\":\"本周\",\"from_date\":\"2016-10-17\",\"to_date\":\"2016-10-20\",\"filter\":{}}"
}

+ Response 200 (application/json)

{
    "id": 1  //书签id      
}

2.6. 获取书签配置

> [GET /bookmarks/bookmark/{bookmarkId}]

书签配置包括类型、名称和具体的查询条件。

+ Response 200 (application/json)

{
  "id" : 26,
  "type" : "/segmentation/",
  "name" : "过去一周每个品类的每日浏览总数",
  "data" : "{\"unit\":\"day\",\"filter\":{},\"by_fields\":[\"event.ViewProduct.ProductType\"],\"chartsType\":\"line\",\"to_date\":\"2015-08-28\",\"from_date\":\"2015-05-29\",\"measures\":[{\"event_name\":\"ViewProduct\",\"aggregator\":\"general\"}]}",
  "time" : "1 week",
  "create_time" : "2015-08-29 04:09:24",
  "user_id" : 1,
  "dashboards" : [ 5 ],
  "project_id" : 1
}

2.7. 删除一个数据概览中的书签

> [DELETE /bookmarks/bookmark/{bookmarkId}]

3. 用户分群

1.13 的分群 API 相对于 1.12 版本,有不兼容的改动。详情请参考两个版本各自的文档。

用户分群

4. 埋点统计

埋点统计 API

5. 用户 TOKEN

使用 API_SECRET 可以满足各种查询需求,但如果希望获取与某个唯一用户对应的 ACCESS_TOKEN 可以参考本节的方法。当获取到 ACCESS_TOKEN 后,请求不需要再使用 API_SECRET。该 ACCESS_TOKEN 与每个项目中的用户账号唯一对应,可使用的权限与该用户在这个项目中分配角色所授予的数据查看和事件使用权限保持一致。

  • 仅当需要进行“与某个用户相关的操作”时才需使用“用户 TOKEN”,例如为某个用户设置概览。若仅使用查询 API,请参考 [API 文档](api.md) 的 1. 调用方法 使用 `$API_SECRET` 即可;
  • 对于每个用户,最多同时有效的 ACCESS_TOKEN 为 20 个。当一个用户已经有 20 个 ACCESS_TOKEN 时,再获取新的 ACCESS_TOKEN 将使该用户之前有效的 ACCESS_TOKEN 里面获取时间最早的一个失效;
  • 使用浏览器通过神策界面进行登录获取的 ACCESS_TOKEN 与通过该 API 获取的等价,上一条的 20 个限制同样适用,例如通过 API 获取时触发 20 个上限,淘汰了用界面登录保存在浏览器里的 ACCESS_TOKEN,则将导致浏览器的登录失效;

5.1. 获取 ACCESS_TOKEN

5.1.1. 使用 API_SECRET 并指定用户名来获取该用户的 ACCESS_TOKEN,使用 curl 访问:

curl -v 'http://$WEB_URL/api/auth/login?token=$API_SECRET&project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"username":"user1"}'

Response 样例:

{
    "role":0,
    "user_id":7,
    "token":"de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b",
    "username":"user1",
    "event_permission":{
        "type":"ALL",
        "events":[]
    }
}

5.1.2. 神策系统版本 < 1.15 时,使用用户名和密码模拟登录获取该用户的 ACCESS_TOKEN,使用 curl 请求命令如下:

curl -v 'http://$WEB_URL/api/auth/login?project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"username":"user1","password":"123456"}'

Response 样例:

{   
    "role":0,
    "user_id":7,
    "token":"de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b",
    "username":"user1",
    "event_permission":{
        "type":"ALL"
        "events":[]
    }
}


注意:

  1. 1.13.5619 及之后某个版本支持开通验证码的方式登录,如果客户开启验证码的方式的登录,通过上述方式获取 ACCESS_TOKEN 时会提示“验证码错误或者已过期”。建议直接用 API_SECRET 的方式获取 ACCESS_TOKEN。
  2. 目前仅支持项目账号通过此方式获取Token.

5.1.3. 神策系统版本 >= 1.15 时,使用用户名和密码模拟登录获取该用户的 ACCESS_TOKEN,使用 curl 请求命令如下:

curl -v 'http://$WEB_URL/api/v2/auth/login?project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"account_name":"user1","password":"123456", "expired_interval": 259200}'

Response 样例:

{   
    "account_name":0,
    "account_id":7,
    "session_id":"de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b"
}


注意:

  1. 1.13.5619 及之后某个版本支持开通验证码的方式登录,如果客户开启验证码的方式的登录,通过上述方式获取 ACCESS_TOKEN 时会提示“验证码错误或者已过期”。建议直接用 API_SECRET 的方式获取 ACCESS_TOKEN。
  2. 如果使用的是平台账号,务必在请求的 URL 中增加参数"is_global=true".

5.1.4. 指定 ACCESS_TOKEN 的过期时间

在 1.13 以及之前的版本,access_token 的有效期默认是 7 天。(这个 7 天是指距离最后一次访问时的时间间隔)。1.14 版本及之后的版本,access_token 的有效期默认是 30 分钟。

在 1.12 以及之后的版本中,可通过指定时间来延长 access_token 的过期时间,最长可延长到六个月的时间。请求样例如下:

curl -v 'http://$WEB_URL/api/auth/login?token=$API_SECRET&project=$PROJECT' \
-X POST -H 'Content-Type: application/json' \
--data '{"username":"user1", "expired_interval": 259200}'


返回结果与普通的获取 ACCESS_TOKEN 相同。其中请求的参数中,通过 expired_interval 指定过期时间,单位为分钟。示例中 259200 分钟即为最长的过期时间: 180 天。这个过期时间,是指 距离最后一次 请求的时间,并不是生成 ACCESS_TOKEN 的时间。也就是说,只有 你180 天没有使用该账号访问过系统,或者没有使用这个 ACCESS_TOKEN 请求数据,才会过期。

注意:删除账号或者修改账号密码,之前获取的 ACCESS_TOKEN 都会失效。

5.1.5. 使用 ACCESS_TOKEN

上一节的 Response 中的 token 字段即该用户的 ACCESS_TOKEN,其他 API 请求使用该 ACCESS_TOKEN 可通过指定 Header `sensorsdata-token`,例如查询事件分析报告使用 ACCESS_TOKEN:

curl -v 'https://saasdemo.cloud.sensorsdata.cn/api/events/report' \
-H 'sensorsdata-token: de4dbc9ec0ba6f9e1d674bcaf1da4861c29f1bcf258107befe91009503072707e6ce4fef6b8522b397b43f8e9fd234967caf8fea0ef5f0022c851df846b0401b' \
-H 'Content-Type: application/json' \
--data-binary '{
    "measures":[
        {
            "event_name":"FinalConvert",
            "aggregator":"SUM",
            "field":"event.FinalConvert.contract_value"
        }
    ],
    "unit":"day",
    "by_fields":[
        "event.FinalConvert.product_type"
    ],
    "to_date":"2016-08-14",
    "from_date":"2016-08-14"
}'