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

神策分析除了强大的 UI 分析界面，还提供了完善的 API。


API 大致可以分为两类:

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

1. 调用步骤：

1.1. 拼接请求地址

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


2.2 版本以下界面入口：【基本设置】->【API_SECRECT】

2.2 版本及以上界面入口：【系统设置】-【项目设置】



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

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

注意事项：

  • 修改 admin 帐号的密码会使 API_SECRECT 发生改变。
  • 所有项目的 API_SECRECT 仅能访问该项目的数据，一定要登录到具体项目后获取该项目的 API_SECRECT。
  • API_SECRECT 和导入数据使用的 token 没有任何关联。

1.2. 快速获取请求参数

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

如下：

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

步骤如下：

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



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

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

2. 用户 TOKEN

该 ACCESS_TOKEN 与每个项目中的用户账号唯一对应，可使用的权限与该用户在这个项目中分配角色所授予的数据权限和功能使用权限保持一致。

2.1. 使用场景

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

2.2. 使用限制

2.2.1.  个数限制

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

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

2.2.2.  有效期限制

ACCESS_TOKEN 的有效期默认是 30 分钟，可通过 expired_interval 指定有效期，是单位是分钟。上限是 259200 分钟 （180天），access_token 的有效期是指距离该账号用户最后一次 请求的时间。即只有 你180 天没有使用该账号访问过系统，或者没有使用这个 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", "expired_interval": 259200}'
    TEXT

注意事项：

  • 删除账号或者修改账号密码，之前获取的 ACCESS_TOKEN 都会失效。
  • access_token 的有效期是指距离该账号用户最后一次 请求的时间。即180 天没有使用该账号访问过系统，或者没有使用这个 ACCESS_TOKEN 请求数据，才会过期。

2.3. 获取 ACCESS_TOKEN

两种方式：

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

2.3.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"}'
    TEXT

  • Response 200

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

2.3.2. 使用用户名和密码模拟登录获取该用户的 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}'
    TEXT

  • Response  200

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

注意事项：

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

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