如何调用管理平台API

在调用管理平台API之前，请先阅读以下信息，以便您更好的集成相关接口。

API主机

由于私有化部署差异，请联系专属客户经理获取适用于您当前私有化环境的API主机地址

基本概念

访问令牌

访问令牌（AccessToken）是直接代表用户请求信息的凭证。访问令牌是一个 JWT格式的字符串，详细信息参见RFC 7519。

其中用户需要关注 Claims 中的 exp（Expires），该字段是一个 UnixTimestamp，其标识了访问令牌的过期时间，请求发起前调用者需要知道 AccessToken 是否过期，若过期了需要进行刷新。

使用过期或无效的访问令牌请求业务接口，将返回未授权或授权无效（HTTP 401）

刷新令牌

刷新令牌（RefreshToken），一般 AccessToken 的有效时间都较短，AccessToken 过期后调用者可以通过 RefreshToken 进行续约操作，避免需要再次使用用户的实际授权信息或操作（账号密码等）。

刷新令牌一般时效性较长，但它是一次性的，并且与特定的 AccessToken 成对使用。

调用请求

在需要身份验证的接口中，在 HTTP 验证头中附带 AccessToken，例：

客户端实现

客户端获取用户身份授权后保存授权数据（AccessToken、RefreshToken）

客户端（调用方）每次发起业务 API 的请求（需要授权的）检查 AccessToken 的过期时间（可以预留一定的时差阈值）

未过期直接发起请求即可，若过期后通过续租授权接口，获取新的授权

续租授权成功返回新的授权后，替换本地保存的授权信息，并使用新的 AccessToken 发起请求

刷新 API 返回 401，表示用户身份授权已失效，需要用户重新进行身份授权（登录）操作

调用示例

以cURL为例，调用接口的流程示例如下

获取身份授权

再调用业务之前，您需要先使用账号密码获取身份授权凭证，即AccessToken，用于后续业务接口的鉴权传参。

// 响应结果如下：
HTTP/2 200 
date: Wed, 02 Apr 2025 07:50:09 GMT
content-type: application/json

{
  "access_token": "<accessToken>",
  "refresh_token": "<refreshToken>",
  "refresh_ttl": 2592000
}

在得到accessToken之后，您可以自行按照JWT规范解析该值，拿到Token的过期时间，以便进行必要的缓存管理。

示例接口：获取主机列表

在确保拿到的AccessToken在有效期内时，按照接口文档所示要求，将其传入Header中的Authorization参数用于鉴权

curl -X GET 'https://<yourApiHost>/remotes?offset=0&limit=10' -H 'Authorization: Bearer <accessToken>'

// 响应结果如下：
HTTP/2 200 
date: Wed, 02 Apr 2025 07:48:02 GMT
content-type: application/json; charset=utf-8
access-control-expose-headers: Content-Range
content-range: row 0-10/2469

[
  {
    "remote_id": 3328,
    "mac": "8C:EC:4B:D2:30:96",
    "owner_id": 1,
    "statuscode": 2707,
    "client": "SLRC_WINDOWS",
    "info": {
      "remote_id": 3328,
      "name": "DESKTOP-5HTLB9D",
      "pc_name": "DESKTOP-5HTLB9D",
      "cpu": "Intel(R) Core(TM) i3-8100 CPU @ 3.60GHz",
      "memory": "12112MB",
      "os_name": "Windows 10 Pro",
      "base_board": "Dell Inc. 0HVPDY",
      "video_controller": "Intel(R) UHD Graphics 630",
      "network_adapter": "Realtek PCIe GbE Family Controller",
      "versioncode": "18234",
      "version": "5.4.3.18234",
      "os": "Windows 10 Pro",
      "contactemail": "SLRC_WINDOWS_ENTERPRISE"
    },
    "state": {
        //...
    },
    "limit_control": "0"
  },
  {
      //...
  }
]

API主机#

基本概念#

访问令牌#

刷新令牌#

调用请求#

客户端实现#

调用示例#

获取身份授权#

示例接口：获取主机列表#