功能 API

最后更新于:2018-10-25 12:04:06

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

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

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

1. 调用方法

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

2. 数据概览

2.1 增加数据概览

[POST /dashboards]

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

2.2 删除数据概览

[DELETE /dashboards/{dashboardId}]

2.3 获取所有数据概览

[GET /dashboards]

  • Response 200 (application/json)

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

[GET /dashboards/{dashboardId}]

  • Response 200 (application/json)

2.5 保存书签到数据概览

[POST /bookmarks/bookmark]

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

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

2.6 获取书签配置

[GET /bookmarks/bookmark/{bookmarkId}]

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

  • Response 200 (application/json)

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

[DELETE /bookmarks/bookmark/{bookmarkId}]

3. 用户分群

3.1 添加一个分群

[POST /segmenter/rule]

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

3.2 执行一个分群

[POST /segmenter/execute/{segmenterId}]

3.3 获取一个分群的执行状态

[POST /segmenter/status]

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

3.4 删除一个分群

[DELETE /segmenter/rule/{segmenterId}]

3.5 获取所有分群

[GET /segmenter/rule/all]

  • Response (application/json)

4. 埋点统计

4.1 获取埋点来源

[GET /data_source/category]

注意:此 API 只支持 1.12 之后的版本,如果为 1.11 及之前,请参考: https://sensors-analytics.readme.io/v1.11/reference#get_data-source-report

使用该 API 获取当前埋点数据(一般只有最近7天的数据)的来源信息:APP 版本号、导入方式。

后续可以根据来源信息获取指定 APP 版本和指定导入方式的埋点报告信息。

  • Request GET /data_source/category

  • Response 200 (application/json)

4.2 获取埋点统计报告

[POST /data_source/report]

注意:此 API 只支持 1.12 之后的版本,如果为 1.11 及之前,请参考: https://sensors-analytics.readme.io/v1.11/reference#get_data-source-report

使用该 API 可以获取埋点统计报告。一般情况下,埋点数据仅保存最近 7 天数据。

若不指定查询区间,默认查询最近 1 小时的埋点统计。查询的运行时间与查询区间正相关,请合理配置查询区间,不要设置过大。

出现已导入大于已读取有可能是正常的,因为这是不同模块的统计结果,有可能这段时间没有读取和校验数据,但另一个模块正在导入之前校验成功的数据。

埋点统计的时间是实际进行导入的时间,如今天导入了前天的一条数据,这条数据会被统计到今天的报告里。

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

5. 用户 TOKEN

使用 API_SECRET 可以满足各种查询需求,但如果希望获取与某个唯一用户对应的 ACCESS_TOKEN 可以参考本节的方法。当获取到 ACCESS_TOKEN 后,请求不需要再使用 API_SECRET。该 ACCESS_TOKEN 与唯一用户对应,对用户设置的权限也相应生效。

  • 仅当需要进行“与某个用户相关的操作”时才需使用“用户 TOKEN”,例如为某个用户设置概览。若仅使用 查询 API ,请参考 API 文档 的 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

使用 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.2 使用 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"
}'