数据提取 API
简介
本节介绍如何使用 HTTP API 从 Gear Studio 平台提取数据,例如:
- 提醒:该 API 可以提取平台中创建的所有提醒的定义,并支持多种筛选方式。
- 警报:该 API 可以提取平台中记录的所有历史警报,并支持多种筛选方式。
- 端点数据:该 API 可以提取与端点相关的所有历史信息,并支持多种筛选方式。
- 地理围栏:该 API 可以提取为每个客户配置的地理围栏列表,包括其中所含的车辆列表。
入门
创建访问令牌
与其他任何 HTTP 集成一样,需要创建访问令牌。此页面包含有关管理访问令牌的更多信息。访问令牌可用于控制任何操作所使用的访问权限。
使用访问令牌进行身份验证
在所有 API 中,访问令牌都可以通过 Authorization 请求头发送,如下所示:
Authorization: Bearer {accessToken}如果无法通过 Authorization 请求头发送令牌,也可以通过 URL 中的 "accessToken" 参数发送访问令牌,如下例所示:
https://gear.cloud.studio/api/v2/alarms?accessToken={accessToken}&clientID=4&maxCount=10API 调用
要调用 API,请查看以下各节中的相关信息:
错误
调用失败时,API 会返回 HTTP 状态码 500 以及如下格式的 JSON 正文,无论错误原因为何(令牌无效、缺少权限或参数无效):
{
"Exception": {
"ClassName": "ServiceException",
"FaultCode": "8001",
"FaultData": "",
"Message": "Description of the error"
}
}- FaultCode:数字错误代码。它在各版本之间保持稳定,集成应依据此字段决定如何处理。
- Message:便于阅读的错误描述。其措辞可能会变化,且返回的是翻译后的文本,因此集成不应依赖其内容。
- FaultData:附加错误数据,通常为空。
最常见的代码如下:
| FaultCode | 含义 | 处理方式 |
|---|---|---|
| 8001 | 访问令牌缺失、不存在或已过期 | 检查令牌或创建新令牌 |
| 8002 | 访问令牌有效,但其账户已被停用 | 重新激活该账户,或使用其他账户的令牌 |
| 8000 | 该令牌无权使用此 API | 使用具有该权限的账户创建令牌 |
| 8004 | 该令牌对所请求的资源(客户、设施、设备或端点)没有权限 | 只请求该账户可以访问的资源 |
| 100000 | 缺少必填值 | 检查调用参数 |
| 100004 | 某个参数的值无效或超出限制 | 检查 Message 中指明的值 |
| 100001 | 服务器意外错误 | 稍后重试;如果问题持续存在,请联系技术支持 |
错误 8000、8001、8002、8004、100000 和 100004 无法通过重试同一调用来解决:请先修正请求或令牌。
最后更新于