API 文档

步骤一：创建 AccessKey

调用 API 时使用 AccessToken 进行认证。先创建 AccessKey，再用它换取访问令牌。

用户 AccessKey 用于操作该用户相关的数据；管理员 AccessKey 用于操作该管理员有权限管理的数据。请按调用方身份选择对应类型。

用户 AccessKey：v0.2.1 及以上

在管理系统中打开“平台用户”，进入对应用户的“详情”，再到“API AccessKey”创建密钥。

商业版用户自行创建

商业版用户也可以在用户平台的“访问控制”页面点击“创建AccessKey”。

管理员 AccessKey：v0.2.3 及以上

在管理系统中打开“系统用户”，进入对应用户的“详情”，再到“API AccessKey”创建密钥。

步骤二：获取 AccessToken

向 /APIAccessTokenService/getAPIAccessToken 发起 POST 请求，提交 AccessKey 信息。此接口用于获取令牌，因此不需要预先携带 X-Edge-Access-Token。

请求体使用 JSON，并设置 Content-Type: application/json。先确认响应的 HTTP 状态码为 200，再检查响应 JSON 中的 code；code 为 200 表示获取令牌成功，其他值表示失败。

以下请求展示管理员类型。用户 AccessKey 应将 type 改为 user，其他字段使用对应用户自己的密钥。

type

身份类型。管理员使用 admin，用户使用 user。

accessKeyId

步骤一中创建的 AccessKey ID。

accessKey

与该 AccessKey ID 对应的密钥。

POST /APIAccessTokenService/getAPIAccessToken

{
  "type": "admin",
  "accessKeyId": "YOUR_ACCESS_KEY_ID",
  "accessKey": "YOUR_ACCESS_KEY"
}

{
  "code": 200,
  "data": {
    "token": "YOUR_ACCESS_TOKEN",
    "expiresAt": 1609686945
  },
  "message": "ok"
}

获取令牌的 cURL 示例

请将示例 IP 地址、端口、YOUR_ACCESS_KEY_ID 和 YOUR_ACCESS_KEY 替换为你自己的 HTTP API 地址与密钥。管理员和用户分别使用对应类型的 AccessKey。

curl -v -X POST \
  -H 'Content-Type: application/json' \
  'http://192.168.1.6:8004/APIAccessTokenService/getAPIAccessToken' \
  -d '{
    "type": "admin",
    "accessKeyId": "YOUR_ACCESS_KEY_ID",
    "accessKey": "YOUR_ACCESS_KEY"
  }'

curl -v -X POST \
  -H 'Content-Type: application/json' \
  'http://192.168.1.6:8004/APIAccessTokenService/getAPIAccessToken' \
  -d '{
    "type": "user",
    "accessKeyId": "YOUR_ACCESS_KEY_ID",
    "accessKey": "YOUR_ACCESS_KEY"
  }'

令牌内容与有效期

令牌过期后，需要重新调用获取令牌接口。

使用同一组 AccessKey 多次获取令牌时，先前获取的 AccessToken 会失效。取得新令牌后，请让后续请求使用最新的 token。

token

访问令牌。调用其他接口时，将此值放入 X-Edge-Access-Token HTTP Header。

expiresAt

令牌过期时间戳。有效期以接口实际返回的时间为准，不应假定固定的小时数；上方时间戳仅用于展示响应结构。

步骤三：携带令牌调用接口

在接口目录中找到需要调用的方法，将请求发往“API接口地址/服务名/方法名”。

使用 POST 发送完整的 JSON 请求体，并在 HTTP Header 中携带步骤二返回的 token。下面的 YOUR_ACCESS_TOKEN 需要替换为该实际值。

Content-Type: application/json
X-Edge-Access-Token: YOUR_ACCESS_TOKEN