API

本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询神策值班同学获取一对一的协助。
神策分析除了强大的 UI 分析界面，还提供了完善的 API。

API 大致可以分为两类:

查询 API: 与分析模型能力一致，主要用于获取各种数据分析报告以及用户列表；
功能 API: 包括概览管理 API 和用户群管理 API ;

调用步骤：

这里以基于“API_SECRET的认证方式”为例，如果希望使用“用户ACCESS_TOKEN”的认证方式，请参考章节2“用户 ACCESS_TOKEN”的认证方式。

拼接请求地址

API 采用标准 HTTP / HTTPS 方式请求，完整的 URL 结构分为：

http(s)://$WEB_URL/api/$API_URL?token=$API_SECRET&project=$PROJECT

请求地址结构	含义	如何获取
$WEB_URL	神策分析访问地址
$API_URL	具体方法 API	如：事件分析模型的 API 为 /events/report
$PROJECT	项目英文名	登录具体项目后，在浏览器地址中截取 url 地址中 project 参数对应的值。
$API_SECRET	用户权限认证的 token	注意：需要使用 admin 账号获取 2.2 版本以下界面入口：【基本设置】->【API_SECRET】 2.2 至 2.5 版本界面入口：【系统设置】-【项目设置】 3.0 版本及以上界面入口：【项目设置】-【基本设置】-【查看 API Secret】

按照上述方式最终可以拼接得到的请求地址示例：（示例不能用于直接使用）

https://family.demo.sensorsdata.cn/api/funnel/report?token=xxxxxxxxxx&project=EbizDemo

注意事项：

修改 admin 帐号的密码会使 API_SECRET 发生改变。
平台管理员的 API_SECRET 可以访问所有项目的数据，项目管理员的 API_SECRET 仅能访问该项目的数据。
API_SECRET 和导入数据使用的 token 没有任何关联。

快速获取请求参数

因为大部分查询 API 的参数结构都比较复杂，初次使用的时候往往不好组织。这里建议大家可以通过浏览器访问神策分析平台来获取需要的参数。方法

如下：

以 Chrome 浏览器获取事件分析报告 /events/report 请求参数为例：

步骤如下：

在 Chrome 中打开神策，在事件分析模型中配置查询条件
打开浏览器的开发者工具，操作方式如截图

点击查询后，在控制台 network 中，使用过滤器过滤 [/events/report] ，过滤出目标 url 后，在右边栏找到 Request Payload 点击 view parsed，即可复制出目标请求参数。

使用 curl 请求

拼接好地址并修改好参数后就可以使用任意 HTTP Client 进行 API 调用了。

curl 示例：

curl 'https://saasdemo.cloud.sensorsdata.cn/api/events/report?token=53f48d27f5ed6e701241d7548093274533d0af3d9d2ae80740a629836897900d' \
-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"
}'

用户 ACCESS_TOKEN

该 ACCESS_TOKEN 与每个项目中的用户账号唯一对应，可使用的权限与该用户在这个项目中分配角色所授予的数据权限和功能使用权限保持一致。而且 ACCESS_TOKEN 与API_SECRET的使用方式不同，无法直接通过请求参数携带ACCESS_TOKEN的方式进行认证，具体用法请参考“2.4. 使用 ACCESS_TOKEN”。

使用场景

需要进行“与某个用户相关的操作”时才需使用“用户 TOKEN”，例如为某个用户设置概览，或者获取某个账号权限范围可见的用群列表等，如果要使用查询API 获取全部事件数据的话，使用 API_SECERT 即可。

使用限制

个数限制

对于每个用户，最多同时有效的 ACCESS_TOKEN 为 20 个。当一个用户已经有 20 个 ACCESS_TOKEN 时，再获取新的 ACCESS_TOKEN 将使该用户之前有效的 ACCESS_TOKEN 里面获取时间最早的一个失效；

使用浏览器通过神策界面进行登录获取的 ACCESS_TOKEN 与通过该 API 获取的等价，上一条的 20 个限制同样适用，例如通过 API 获取时触发 20 个上限，淘汰了用界面登录保存在浏览器里的 ACCESS_TOKEN，则将导致浏览器的登录失效；

有效期限制

ACCESS_TOKEN 的有效期默认是 30 分钟，可通过 expired_interval 指定有效期，是单位是分钟。上限是 259200 分钟（180天）。

curl 示例：

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 都会失效。
access_token 的有效期是指距离该账号用户最后一次请求的时间。即180 天没有使用该账号访问过系统，或者没有使用这个 ACCESS_TOKEN 请求数据，才会过期。

获取 ACCESS_TOKEN

两种方式：

使用 API_SECRET 指定用户名获取
使用账号名和密码获取

使用 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 200

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

使用用户名和密码模拟登录获取该用户的 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 200

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

注意事项：

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

使用 ACCESS_TOKEN

使用该 ACCESS_TOKEN 可通过指定 Header `sensorsdata-token`，例如查询事件分析报告使用 ACCESS_TOKEN:

curl 示例：

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"
}'