HeyCloud 文档

# API 说明

# API 的调用方法

HeyCloud 的 API 位于部署所在位置的 /api 路径下，例如 HeyCloud 部署在 192.168.1.200 节点上，那么其 API 的根路径就是http://192.168.1.200:9000/heycloud/api，如果 HeyCloud 通过反向代理映射到了 test.geohey.com 域名的 80 端口下，那么 API 的根路径就是http://test.geohey.com/heycloud/api。

HeyCloud 的 API 分为以下的子 API：

  • /base
  • /io
  • /render
  • /data
  • /analytics
  • /routing
  • /monitor
  • /logs

要确认 API 可以访问，可以通过浏览器直接访问某个子 API 的路径，例如：http://host:port/heycloud/api/base，正常情况下应该能得到类似如下的响应：

{
	"result": {
		"name": "heycloud-base-api",
		"version": "0.10.0",
		"commit": "3c62bf885eeec4a2a96af87b4e9d31e2179cbba7"
	}
}

HeyCloud API 的正确响应一般是 JSON 格式，正确的 JSON 格式响应是一个包含result属性的对象；如果是错误的响应，响应的格式会是一个带有error和message属性的对象：

{
	"error": "NOT_ACCESSIBLE",
	"message": "没有权限访问"
}

并不是所有响应都是 JSON 格式，比如地图渲染接口会返回图片、影像数据接口会返回二进制数据。

一般的业务层面的错误返回的是一个正常的 HTTP 响应（200 状态），这意味着请求成功但是处理业务过程发生了错误，但有些情况也会返回一个异常的响应（比如返回了 404 错误）。一般来说，如果响应的数据格式不是 JSON，比如直接返回图片的接口，那么就会带上 HTTP 状态码，因为如果返回 200 状态前端会认为这是一个正确的图片；另外，所有后台未捕获的异常，比如访问数据库出错等等，会返回 500 错误。

# API 的请求身份

API 的请求一般要求附带身份信息，访问 HeyCloud API 的身份有两种：一般帐号和管理员。

对于一般帐号的请求，只需要将帐号的 ID 设置给 API 请求的x-heycloud-account-id属性，可以设置为请求头、也可以设置为 URL 请求参数。建议优先使用请求头，这样可以较好地和请求参数区分开：

curl -H "x-heycloud-account-id: 0472f0d2-d485-444e-97b9-669f564ea358" http://host:port/heycloud/api/data/vdataset/list

对于设置请求头困难的场景，也可以将帐号 ID 直接放入 URL：

curl http://host:port/heycloud/api/data/vdataset/list?x-heycloud-account-id=0472f0d2-d485-444e-97b9-669f564ea358

一般情况下，开发应用并不需要管理员权限，但如果想集成一些管理功能的话就需要用管理员身份。使用管理员身份需要通过登录获取 session 值，然后将 session 值附加到 API 请求的 x-heycloud-admin-session 属性。

# API 的功能

请查阅：API 参考文档

← 常见术语 →