获取机器人信息
概述
- 此 API 用于获取机器人信息；
授权方式
| 数据维度授权 | 企业级授权 | 此 API 为企业级授权，企业级授权和代理商级授权的授权账号均可以调用此 API。请参考 授权方式。 |
|---|
| 接口维度授权 | 默认授权 | 此 API 为默认授权，您无需为您的授权账号额外申请接口维度授权就可以调用。请参考 授权方式。 |
|---|
请求
请求域名
请求协议
| HTTP URL 路径 | /v1/robot/robot_info |
|---|---|
| HTTP Method | GET |
请求 URL 参数
| 参数 | 类型 | 必填 | 参数说明 |
|---|---|---|---|
| robot_sn | string | 是 | 机器人 sn |
| is_report_status | int | 否 | 是否获取机器人上报的当前状态信息（当前电量、当前任务和当前位置等），默认不获取。 0：不获取 1：获取 |
| is_report_task_event | int | 否 | 是否获取机器人上报的任务事件信息，默认不获取。需要和 report_task_type 参数配合使用才能生效。只能获取到最近 24 小时内的上报任务事件。 0：不获取 1：获取 |
| report_task_type | string | 否 | 需要获取的机器人上报的任务事件的任务类型，多个用英文逗号分隔。仅当参数 is_report_task_event=1 的时候有效。支持的任务类型如下：
|
请求 cURL 示例
# 请根据您的区域替换域名 curl --location 'https://openapi.orionstar.com/v1/robot/robot_info?robot_sn=test_sn' \ --header 'Authorization: Bearer YOUR-ACCESS-TOKEN'
响应
公共响应体
| 参数 | 类型 | 参数说明 |
|---|---|---|
| code | int | 错误代码。0 是成功，非 0 是失败，请参考 错误代码。 |
| msg | string | 错误描述，当失败的时候会给出具体的错误描述。 |
| req_id | string | 日志跟踪 id，当遇到问题需要猎户星空协助查问题时候，请提供此跟踪 id 值。 |
| data | object | 业务数据 data 对象，详见下述 响应体 data 对象。 |
响应体 data 对象
| 参数 | 类型 | 参数说明 |
|---|---|---|
| corp | object | 机器人所属的 corp 企业信息对象，请参考 corp - 企业信息对象。 |
| robot | object | robot 机器人信息对象，请参考 robot - 机器人信息对象。 |
| robot_report_status | object | 机器人上报的当前状态信息对象，仅当请求参数 is_report_status=1 的时候返回。请参考 robot_report_status - 机器人当前状态信息。 |
| robot_task_list | array | 机器人上报的任务事件信息对象列表数组，数组的每个元素都是一个 robot_task 机器人任务事件信息对象，只能获取到最近 24 小时内的上报任务事件。仅当 is_report_task_event=1 且 report_task_type 传递了正确的任务类型的时候返回。请参考 robot_task - 机器人任务事件信息。 |
corp - 企业信息对象
| 参数 | 类型 | 参数说明 |
|---|---|---|
| ov_corpid | string | 企业 id |
| corp_name | string | 企业名称 |
| create_time | string | 创建时间，整数时间戳，单位是秒。 |
| update_time | string | 最后修改时间，整数时间戳，单位是秒。 |
robot - 机器人信息对象
| 参数 | 类型 | 参数说明 |
|---|---|---|
| ov_corpid | string | 所属企业 id |
| robot_uuid | string | 机器人 uuid |
| robot_sn | string | 机器人 sn |
| robot_name | string | 机器人名称 |
| robot_version | string | 机器人 ROM 版本号，例如：V9.7.2024041200.1234US |
| robot_model | string | 机器人型号，例如：OS-R-DR01S |
| bind_time | string | 最后一次绑定到当前企业的时间。整数时间戳，单位是秒。例如：1711966681。 |
| expires_time | string | 租期的截止时间，仅租用的机器人有效。整数时间戳，单位是秒。例如：1711966681。 |
| online_status | string | 机器人在线状态。在线状态是根据机器人发送的心跳来判断的，状态更新会有大约 15 秒的延迟。 0：不在线 1：在线。 |
robot_report_status - 机器人当前状态信息
| 参数 | 类型 | 参数说明 |
|---|---|---|
| battery | object | 机器人当前电量信息 |
| battery.battery_rate | string | 当前电量剩余百分比 |
| battery.is_charging | string | 是否处于充电状态。 0：否 1：是 |
| task_info | object | 机器人当前任务信息对象 |
| task_info.task_name | string | 机器人当前执行的任务名称，例如：送餐中 |
| task_info.last_task_name | string | 机器人上一次执行的任务名称，例如：等待送餐 |
| location | object | 机器人当前位置信息对象 |
| location.state | string | 机器人定位状态。 ready：定位成功 get_lost：定位失败 |
| location.pos_name | string | 机器人当前位置的默认语言名称 |
| location.pos_all_name | object | 机器人当前位置的多语言名称信息对象 |
| location.pos_all_name.zh_CN | string | 机器人的当前位置，中文。仅当机器人上报了中文的当前位置才有效，如果没有上报则是空串。 |
| location.pos_all_name.en_US | string | 机器人的当前位置，英文。仅当机器人上报了英文的当前位置才有效，如果没有上报则是空串。 |
| location.emergency | string | 是否处于急停状态。 0：否 1：是 |
robot_task - 机器人任务事件信息
| 参数 | 类型 | 参数说明 |
|---|---|---|
| task_id | string | 任务 id |
| task_type | string | 任务类型。定义如下：
|
| event_type | string | 此任务最后一次上报的事件类型。不同的任务类型会有不同的事件类型，定义如下：
|
| task_time | string | 任务的创建时间，整数时间戳，单位是秒。 |
| start_time | string | 任务的开始时间，整数时间戳，单位是秒。 |
| update_time | string | 任务的最后上报时间，整数时间戳，单位是秒。 |
| task_data | object | 任务数据。不同的任务类型会有不同的任务数据，数据结构定义如下：
{ "pos_name" : "A01" // 目的点位名称 } |
| event_list | array | 此任务上报的所有事件列表，请注意此列表来源于机器人上报，由于机器人可能上报的不完整(例如网络不稳定），所以其包含的事件不能保证是完整的。结构示例如下： [ { "event_type": "te__start", // 事件类型 "first_time": "1641881442", // 此实事件的首次上报时间 "last_time": "1641881442" // 此事件的最后上报时间 }, { "event_type": "te_arrived", "first_time": "1641881443", "last_time": "1641881443" }, { "event_type": "te__end", "first_time": "1641881444", "last_time": "1641881444" }, // ... 省略其他任务事件 ] |
| event_list[].event_type | string | 事件类型 |
| event_list[].first_time | string | 此实事件的首次上报时间，整数时间戳，单位是秒。 |
| event_list[].last_time | string | 此事件的最后上报时间，整数时间戳，单位是秒。 |
响应体示例
{ "code": 0, "msg": "", "data": { // 企业信息 "corp": { "ov_corpid": "orion.ovs.entprise.12345678", "corp_name": "测试企业", "create_time": "1711966681", "update_time": "1711966681" }, // 机器人信息 "robot": { "ov_corpid": "orion.ovs.entprise.12345678", "robot_uuid": "test_uuid", "robot_sn": "test_sn", "robot_name": "小豹", "robot_version": "V9.7.2024041200.1234US", "robot_model": "OS-R-DR01S", "bind_time": "1711966681", "online_status": "1" }, // robot_report_status 对象是机器人的当前状态信息，仅当请求参数 is_report_status=1 的时候返回 "robot_report_status": { "battery": { "battery_rate": "85", "is_charging": "0", "update_time": "1712046236" }, "task_info": { "task_name": "送餐中", "last_task_name": "等待送餐", "update_time": "1712046236" }, "location": { "state": "ready", "pos_name": "A01", "pos_all_name": { "zh_CN": "A01", "en_US": "" }, "emergency": "0", "update_time": "1712046236" } }, // robot_task_list 对象是机器人的当前任务事件信息列表，仅当请求参数 is_report_task_event=1 且 report_task_type 传递了正确的任务类型的时候返回 "robot_task_list": [ { "task_id": "test_task_id", "task_type": "meals_deliver_task-deliver", "event_type": "te__end", "task_time": "1712046163", "start_time": "1712046163", "update_time": "1712046237", "task_data": { "pos_name": "A01" }, "event_list": [ { "event_type": "te__start", "first_time": "1712046163", "last_time": "1712046163" }, { "event_type": "te_arrived", "first_time": "1712046236", "last_time": "1712046236" }, { "event_type": "te__end", "first_time": "1712046237", "last_time": "1712046237" } ] } ] } }