密级公开
版本10D.2

AICP 系统服务接口开发手册

1. 概述#

灵云平台除了提供能力服务接口外，还提供四个辅助性的系统服务接口。

接口名称功能
get-access-token获取访问令牌，以用于能力服务接口的调用
get-service-url获取能力服务入口地址
check-auth获取本地能力授权信息
get-conf获取运营配置

所有系统服务接口均只支持 https 协议访问，而且必须使用标准的 Basic Access Authentication 进行用户身份的认证。后续文档中会使用简称 BASIC 认证

2. 认证方式#

在使用 BASIC 认证方式进行认证时，使用 appkey 作为用户名，使用 secret 作为密码。根据 RFC2617 中的要求，请求中应包含 Authorization 头。若用户名是 "Aladdin", 密码是 "open sesame", 请求中会包含 HTTP 头 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==，通过计算 base64("Aladdin:open sesame") 得到 QWxhZGRpbjpvcGVuIHNlc2FtZQ==

若请求中未使用 BASIC 认证方式，或使用了其他方式，亦或 appkey 和 secret 不正确时，服务会返回 HTTP/1.1 401 Unauthorized 响应，并设置 HTTP 头 WWW-Authenticate: Basic realm="WallyWorld"。其中 WallyWorld 是服务端一个可配置的字符串。

3. 接口定义#

3.1 get-access-token#

本接口用于获取或者更新访问令牌，以用于能力服务接口调用。

  • 访问令牌具有时效性，默认为一天，从令牌被创建的时刻算起
  • 访问令牌是与 appkey 绑定的，使用 appkey1 获得的令牌不能用于 appkey2
  • 同一 appkey 下可以有多个访问令牌并存
  • 获取或更新的访问令牌均可额外获得一个 refresh_token 用于后续更新
  • 使用 refresh_token 更新访问令牌，会将旧令牌有效时长缩短为五分钟，同时获得一个新令牌。
  • 使用 refresh_token 更新访问令牌，若无法找到旧令牌，操作不失败，仍可获得一个新令牌。

3.1.1 URL#

GET https://[hostname[:port]]/v10/auth/get-access-token

3.1.2 请求#

  • BASIC 认证输入：appkey, secret
  • URL 参数输入:
名称约束描述
appkey必选必须与 BASIC 认证中的 appkey 一致
udid可选灵云 SDK 提供此参数，非 SDK 应用可以不提供
refresh_token可选更新访问令牌时提供

3.1.3 响应#

  • BASIC 认证失败时的响应，请参考章节认证方式
  • BASIC 认证中的 appkey 与 URL 中的 appkey 不匹配时，返回 HTTP/1.1 400 Unmatch appkey 响应
  • 操作失败时，返回 HTTP/1.1 500 Internal Server Error 响应
  • 操作成功时，返回 HTTP/1.1 200 OK 响应，并返回格式为 application/json 的包体，包体中包含如下字段
字段名类型说明
tokenstring访问令牌
refresh_tokenstring用于更新令牌的 token
lifenumber访问令牌有效时长，单位: second

3.2 get-service-url#

TODO: 待补充

3.3 check-auth#

TODO: 待补充

3.4 get-conf#

TODO: 待补充

4. 版本记录#

接口版本平台支持版本组件及支持版本修改内容
10.0.010B.0aicp_apigw 10.0.0组件发生变化，接口未更改
10.0.010A.0aicp_http 10.0.0初始版本