机器人任务事件回调
概述
- 您需提供回调 URL 注册到猎户星空的系统中,当机器人执行的任务状态发生变化的时候,猎户星空主动回调注册到系统中的回调 URL,用于及时通知您的机器人任务执行状态的变化;
- 机器人任务执行状态回调依赖机器人端的任务执行状态上报,如果猎户星空的服务端接收不到机器人端的上报(例如机器人网络不畅)则无法完成回调;
- 由于回调是异步并行的,因受到您的回调 URL 的响应时间的影响等因素,猎户星空无法保证回调的时序;
回调 URL 要求
- 回调 URL 可以是 HTTP 地址也可以是 HTTPS 地址,建议使用 HTTPS 地址;
- 回调 URL 需要支持 POST 请求,猎户星空会使用 POST 方式进行请求;
- 回调 URL 支持携带参数,参数拼接之后最长不能超过 1KB;
回调时机
- 当机器人执行的任务触发了事件(即 event_type)的时候会立即回调;
- 不同的任务有不同的事件回调,请参考 回调任务和事件列表;
回调请求
回调请求协议
回调请求 Method | POST |
---|---|
回调请求 Content-Type | 您的回调 URL 需要同时支持如下 2 种 Content-Type
|
回调超时时间 | 5秒,响应时间超过 5 秒则放弃本次回调,并且不会重试。 |
回调请求体参数
参数 | 类型 | 参数说明 |
---|---|---|
open_appid | string | 授权账号的 appid |
open_code | string | 由猎户星空颁发的回调鉴权暗码,用于接入方在收到回调请求之后识别是猎户星空的合法请求,而不是非猎户星空的非法请求。鉴权暗码长度为 32 字节。鉴权暗码不能透漏给第三方。 |
robot_sn | string | 机器人 sn |
ov_corpid | string | 企业 id |
task_id | string | 任务唯一 id |
task_type | string | 任务类型,请参考 回调任务和事件列表。 |
event_type | string | 任务事件的类型,不同的任务类型会有不同的事件类型,请参考 回调任务和事件列表。 |
task_data | jsonString | 任务附加数据,格式为 json 对象字符串,可能为空串,例如:{"pos_name":"桌号A01"}。不同的任务类型会有不同的附加数据,请参考 回调任务和事件列表。 |
event_data | jsonString | 任务事件附加数据,格式为 json 对象字符串,可能为空串,例如:{"pos_name":"桌号A01"}。不同的任务事件类型会有不同的附加数据,请参考 回调任务和事件列表。 |
回调请求 cURL 示例
curl --location 'https://your_domain.com/your_callback_url' \ --form 'open_appid=test_appid' \ --form 'open_code=b317979b11292276e0a1b49a08953dec' \ --form 'robot_sn=test_sn' \ --form 'ov_corpid=test_ov_corpid' \ --form 'task_id=85b35e3b5fc452a0f7a6d2a60d9edb9b' \ --form 'task_type=meals_deliver_task-deliver' \ --form 'event_type=te_arrived' \ --form 'task_data={"pos_name":"桌号A01"}' \ --form 'event_data={"pos_name":"桌号A01"}'
回调响应
回调响应 HTTP 状态码 | 200 |
---|
回调任务和事件列表
任务类型 task_type
任务类型 task_type | 说明 |
---|---|
meals_deliver_task-deliver | 送餐到桌任务。给任何 1 桌送 1 次餐即为 1 个送餐到桌任务。 |
meals_deliver_task-return | 送餐返程任务。送餐到桌任务完成之后的返程任务即为 1 个送餐返程任务。 |
任务事件类型 event_type
任务类型 task_type | 任务名称 | 任务事件类型 event_type | 事件说明 |
---|---|---|---|
meals_deliver_task-deliver | 送餐到桌任务 | te__start | 开始执行。请注意此 event_type 包含两个下划线_。 |
te_arrived | 到达目的地。请注意此 event_type 只包含一个下划线_。 | ||
meals_deliver_task-return | 送餐返程任务 | te__start | 开始执行。请注意此 event_type 包含两个下划线_。 |
te__end | 执行结束。请注意此 event_type 包含两个下划线_。 |
任务附加数据 task_data
各任务类型(task_type)的不同任务事件类型(event_type)下的任务附加数据(task_data)
任务类型 task_type | 任务事件类型 event_type | 任务附加数据 task_data |
---|---|---|
送餐到桌任务 meals_deliver_task-deliver | te__start | 无 |
te_arrived | { "pos_name" : "桌号A01" // 目标点位名称 } |
|
送餐返程任务 meals_deliver_task-return | te__start | { "pos_name" : "桌号A01" // 目标点位名称 } |
te_arrived | 同上 |
任务事件附加数据 event_data
各任务类型(task_type)的不同任务事件类型(event_type)下的任务事件附加数据(event_data)
任务类型 task_type | 任务事件类型 event_type | 任务事件附加数据 event_data |
---|---|---|
送餐到桌任务 meals_deliver_task-deliver | te__start | 无 |
te_arrived | { "pos_name" : "桌号A01" // 目标点位名称 } |
|
送餐返程任务 meals_deliver_task-return | te__start | 无 |
te_arrived | { "task_result" : "succ" // 任务执行结果,succ: 成功,skip: 跳过 } |