1. 认证方式概述

针对新提供的 OpenAPI 的相关接口,推荐使用 API-Key 完成 HTTP 接口的认证。然而,针对之前提供的功能 API查询 API以及一些第三方对接的接口只能采用“API_SECRET” 或者 “基于用户名和密码模拟登录”等方式完成 HTTP 接口的认证。



2. API-Key 认证

API-Key 是一个随机生成长度为 35 个字符的文本,用于在发起 HTTP 请求时作为用户的身份标识;当用户在指定项目下分配 API-Key 时,该 API-Key 就会与该用户和项目进行绑定,且无法变更绑定关系;API-Key 的权限与分配该 API-Key 的用户的权限保持一致,当用户的权限调整时,API-Key 的权限也会随着发生变化。

2.1. API-Key 的获取


1. 点击项目设置→ 基本设置,点击“API Key 管理"进入API-Key管理页面。


2. 如果没有 API-Key,点击“新增 Api Key”按钮创建一个新的 API-Key;如果列表中已经存在,直接复制其中未过期的 API-Key 即可;

注意:下图列表中展示的 API-Key 都属于“平台管理员1”关联的“测试项目”,发送 HTTP 请求时该 API-Key 也只能在“测试项目”下使用;


2.2. API-Key 的使用


在 HTTP 请求的请求的 query 或者 header 中携带 API-Key 即可,例如:api-key: #K-fMFGYYlot5H6dxxxxxxxxxxxxxxxxxxxxxx

需要注意的是,一定要在请求的 query 或者 header 中携带项目信息,例如:sensorsdata-project: production

完整的 curl 命令示例如下:

// 将 API-Key 作为 http header 进行传递;
// 注意:由于 API-Key 是在项目下分配的,因此一个 API-Key 只能在一个项目下使用
curl -XGET "http://{host}:8107/api/v3/analytics/v1/project/list" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "sensorsdata-project: default" \
  -H "api-key: {api-key}"
 
 
 
// 如果需要以指定用户身份进行访问,可以通过在 headers 中指定 account-id 实现(注意:仅管理员的 API-Key 支持该用法)
// 通过该方式访问接口时,该接口会以指定用户的身份执行,包括权限和操作日志等都会受到影响;
curl -XGET "http://{host}:8107/api/v3/analytics/v1/project/list" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "sensorsdata-project: default" \
  -H "api-key: {api-key}" \
  -H "account-id: {account-id}"
CODE

更多 API-Key 的产品使用文档请参考:API Key 管理