zh:server_docs:event_callback_guide:robot_alarm_event_callback

机器人预警通知回调

概述

  • 您需提供回调 URL 注册到猎户星空的系统中,当有机器人预警通知的时候,猎户星空主动回调注册到系统中的回调 URL,用于及时通知您的机器人发生了预警;
  • 默认情况下猎户星空不会进行预警通知,如您需要,请联系猎户星空售前技术支持进行申请,请参考 如何申请预警通知回调
  • 由于回调是异步并行的,因受到您的回调 URL 的响应时间的影响等因素,猎户星空无法保证回调的时序;

如何申请预警通知回调

请您按照如下步骤来申请预警通知回调:

  1. 请按照此文档的说明,准备好您的回调 URL;
  2. 登录 企业后台(接待后台),在 <预警定制> 功能页面进行如下配置,此步骤您可以自己操作,也可以联系猎户星空的售前技术支持协助您操作:
    1. 添加一个新的通知人,此通知人后续将专门用于接收警通知回调(下面简称:专用通知人),姓名填写:预警通知回调专用,手机号请暂时填写您能收到短信的手机号(此手机号仅用于配置过程中的测试验证,后续正式配置好回调 URL 之后此手机号会被修改成回调 URL,请您不用担心正式配置好回调 URL 之后收到您不想收到的短信);
    2. 根据您的需要来配置需要回调的预警,例如:离线预警、急停预警等,通知人选择前面添加的专用通知人,并进行测试,如果您收到了符合您预期的预警短信,说明您的配置是正确的,预警的规则请参考 预警通知规则
    3. 请您注意:只有配置了上述专用通知人的预警后续才会进行回调,其他没有配置专用通知人的预警不会进行回调;
  3. 联系猎户星空的售前技术支持,告知您的回调 URL,猎户星空进行回调 URL 配置,配置完成后,专用通知人的手机号将会被替换成您的回调 URL,在企业后台(接待后台)查看此专用通知人的时候手机号会显示为空;
  4. 后续如果您想修改预警通知回调的预警配置,您可以随时修改,只需要把专用通知人配置到您的预警配置中即可收到预警回调;
  5. 请注意:请您务必不要修改或删除此专用通知人,否则可能会收不到回调;

预警通知规则

  • 新激活(绑定)的机器人在 24 小时内不会发送预警通知短信,也不会进行预警通知回调;
    • 这是因为机器人在新激活的 24 小时内一般都处于试运行阶段,初期的运营配置一般都集中在此阶段,可能会有相对频繁的重启和离线,为了防止不必要的预警,猎户星空在机器人激活(绑定)的 24 小时内不会进行预警;
  • 每个机器人的每种类型的预警每天最多预警 3 次,包括预警通知短信和预警通知回调;

回调 URL 要求

  • 回调 URL 可以是 HTTP 地址也可以是 HTTPS 地址,建议使用 HTTPS 地址;
  • 回调 URL 支持携带参数,参数拼接之后最长不能超过 1KB;

回调时机

  • 当发生预警的时候会立即回调;
  • 多个机器人的同类预警可能会进行合并;
  • 因预警有很强的时效性,所以只会回调一次,失败也不会进行重试;

回调请求

回调请求 Method POST
回调请求 Content-Type application/json
回调超时时间 5秒,响应时间超过 5 秒则放弃本次回调,并且不会重试。
参数 类型 参数说明
open_appid string 授权账号的 appid
open_code string 由猎户星空颁发的回调鉴权暗码,用于接入方在收到回调请求之后识别是猎户星空的合法请求,而不是非猎户星空的非法请求。鉴权暗码长度为 32 字节。鉴权暗码不能透漏给第三方。
ov_corpid string 企业 id
alarm_type string 预警类型 id,请参考 预警类型 alarm_type
alarm_config Object 预警配置信息对象,不同的预警类型会有不同的预警配置,请参考 预警配置信息对象 alarm_config 和预警信息对象 abnormal_info 中有关 alarm_config 的说明。
alarm_config.start_time int 此参数可能不存在,只有包含工作时间配置的预警才包含此参数 工作开始时间。从 00:00:00 开始的秒数。预警判断使用北京时区来计算,默认是00:00:00。例如 08:00:00 是 28800。
alarm_config.end_time int 此参数可能不存在,只有包含工作时间配置的预警才包含此参数 工作结束时间。从 00:00:00 开始的秒数。预警判断使用北京时区来计算,默认是23:59:59。例如 22:00:00 是 79200。
robot_list Object[] 预警的机器人和预警信息列表
robot_list[].robot_sn string 机器人 sn
robot_list[].robot_name string 机器人名称
robot_list[].abnormal_info Object 预警信息对象,不同的预警类型会有不同的预警信息,请参考 预警配置信息对象 alarm_config 和预警信息对象 abnormal_info 中有关 abnormal_info 的说明。
robot_list[].abnormal_info.ts int 此参数可能不存在 预警发生的时间,整数时间戳,单位是秒,有一些预警类型并没有此参数,当没有此参数的时候建议使用回调的当前时间作为预警时间。例如:1712634136
{
    "open_appid": "test_appid",
    "open_code": "test_code",
    "ov_corpid": "test_ov_corpid",
    "alarm_type": "2",
    "robot_list": [
        {
            "robot_sn":"test_sn",
            "robot_name": "test_name",
            "abnormal_info": {
                // 预警信息对象,请参考 <预警配置信息对象 alarm_config 和预警信息对象 abnormal_info> 章节中有关 abnormal_info 的说明
            }
        }
    ],
    "alarm_config": {
        // 预警配置信息对象,请参考 <预警配置信息对象 alarm_config 和预警信息对象 abnormal_info> 章节中有关 alarm_config 的说明
    }
}
curl --location 'https://your_domain.com/your_callback_url' \
     --header 'Content-Type: application/json' \
     --data '{
    "open_appid": "test_appid",
    "open_code": "test_code",
    "ov_corpid": "test_ov_corpid",
    "alarm_type": "2",
    "robot_list": [
        {
            "robot_sn":"test_sn",
            "robot_name": "test_name",
            "abnormal_info": {
                "battery_rate": 5
            }
        }
    ],
    "alarm_config": {
        "battery_rate": 10
    }
}'

回调响应

回调响应 HTTP 状态码 200

预警列表

预警类型 id 预警类型名称 预警简介
1 定位预警 如果机器人在线并发生了定位丢失,则告警。
2 电量预警 如果机器人电量低于设置的百分比(例如 10%),且未处于充电状态,则告警。
3 路径预警 如果机器人在执行运动相关的任务时,持续超过 20 秒路径规划失败,则告警。
4 急停预警 如果机器人在线,且在执行任务时被按了急停,且在设置的时间内(例如 5 分钟)未恢复,则告警。
5 离线预警 如果机器人在设置的工作时间范围内(例如 08:00 - 22:00),离线超过设置的时间(例如 30 分钟),则告警。
6 超时预警 如果机器人在设置的工作时间范围内(例如 08:00 - 22:00),处于在设置的状态中(例如 急停)或者正在执行设置的任务(例如 导览),且超过设置的时间(例如 30 分钟),则告警。
7 超频预警 如果机器人在设置的工作时间范围内(例如 08:00 - 22:00),在设置的时间内(例如 30 分钟)执行设置的任务(例如 导览)超过设置的次数(例如 5 次),则告警。
8 位置预警 如果机器人在设置的工作时间范围内(例如 08:00 - 22:00),超过设置的时间(例如 30 分钟)仍没有到达过设置的地点(例如 办公室),则告警。
10 回充预警 如果机器人在自动回冲时,失败次数超过 10 次,则告警。
11 待机预警 如果机器人在设置的工作时间范围内(例如 08:00 - 22:00),持续超过设置的时间(例如 30 分钟)处于未唤醒(表情)状态,则告警。
12 充电异常 如果机器人在充电桩上由于接触不良导致充电缓慢,连续发生设置的次数(例如 3 次),则告警。

预警配置信息对象 alarm_config

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

参数 类型 参数说明
battery_rate int 是预警电量百分比阈值,例如 %10 是 10。

预警信息对象 abnormal_info

参数 类型 参数说明
battery_rate int 是当前电量百分比,例如 %2 是 2。

预警配置信息对象 alarm_config

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

参数 类型 参数说明
timeout int 是超时时间,单位是秒。

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

参数 类型 参数说明
timeout int 是超时时间,单位是秒。

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

参数 类型 参数说明
task_name string 此参数可能不存在 预警任务类型,例如:导览
state_name string 此参数可能不存在 预警状态类型,例如:急停
timeout int 是超时时间,单位是秒。

预警信息对象 abnormal_info

参数 类型 参数说明
task_name string 此参数可能不存在 预警任务类型
state_name string 此参数可能不存在 预警状态类型

预警配置信息对象 alarm_config

参数 类型 参数说明
task_name string 是预警任务类型,例如:导览
frequency int 是预警频次阈值,例如:2
timeout int 是超时时间,单位是秒。

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

参数 类型 参数说明
pos_name string 是预警点位
timeout int 是超时时间,单位是秒。

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

参数 类型 参数说明
timeout int 是超时时间,单位是秒。

预警信息对象 abnormal_info

预警配置信息对象 alarm_config

参数 类型 参数说明
frequency int 是预警频次阈值,例如:5

预警信息对象 abnormal_info

参数 类型 参数说明
battery_rate int 是当前电量百分比,例如 %2 是 2。
  • 最后更改: 2024-06-11 18:51 +0800