跳到內容

送出機械人事件(beta)

Beta
POST
/v1/robots/events
curl --request POST \
--url https://api.example.yas/v1/robots/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "events": [ { "robotId": "rbt_example", "eventId": "evt_1001", "eventStart": "2026-10-15T10:00:00.000Z", "timezone": "Asia/Hong_Kong", "type": "mode_change", "nativeCode": "100", "nativeDescription": "Autonomous moving" } ] }'

Beta。用 server key 送出 1 至 500 筆事件。每筆要有 robotId、eventId、eventStart、timezone、type 與 nativeCode。type 是 mode_change、alarm、intervention、navigation、incident、task_state、software_change 或 proximity。proximity 事件在知道時請送 distanceM、objectMotion 與 subject。這台機械人必須已存在於這個 partnerId。未知的 robotId 是 404,這次什麼都不會存。清單是空的、缺欄位,或 type、objectMotion、subject、resolution、consequence 不在允許的值內,是 400。超過 500 筆是 413。同一 partnerId、robotId 與 eventId 再送,保留第一次。屬於其他 type 的欄位仍會存,不是 400。accepted 是新存的列。duplicates 是本來已有的列。eventIds 按請求順序列出每個 id。accepted 加 duplicates 等於事件筆數。

Request Bodyrequired

小節:Request Bodyrequired
Media typeapplication/json
object
partnerId
required

合作夥伴 id。必須與 server key 相符。

string
schemaVersion
required

這次內容的 schema 版本。例子:2026-11。

string
sourceSystem
required

送出這次內容的系統名稱。例子:partner-export。

string
firmwareVersion

送出時的韌體版本。

string
metadata

合作夥伴的額外欄位。照送出的內容保存。

object
key
additional properties
any
events
required

這次呼叫的事件。送 1 至 500 筆。

Array<object>
>= 1 items <= 500 items
object
robotId
required

機械人 id。這台機械人必須已經存在。

string
eventId
required

合作夥伴的事件 id。同一合作夥伴、機械人與事件 id,保留第一次的內容。

string
eventStart
required

這段事件開始的時間,ISO-8601。

string format: date-time
timezone
required

IANA 時區。例子:Asia/Hong_Kong。

string
type
required

事件種類。

string
Allowed values: mode_change alarm intervention navigation incident task_state software_change proximity
nativeCode
required

合作夥伴對這次事件的代碼。

string
nativeDescription

nativeCode 的合作夥伴說明。

string
taskInstanceId

這次事件所屬的任務實例。沒有就可以不送。

string
siteId

場地 id。

string
zoneId

場地內的區域 id。

string
eventEnd

這段事件結束的時間,ISO-8601。

string format: date-time
updateTime

這次內容最後更新的時間,ISO-8601。

string format: date-time
durationSeconds

這段事件的長度,單位是秒。這不是反應時間。

number
reasonCode

合作夥伴的原因代碼。

string
modeBefore

事件前的運作模式。

string
modeDuring

事件進行中的運作模式。

string
modeAfter

事件後的運作模式。

string
taskStatus

合作夥伴在這次事件上記下的任務狀態。

string
sourceRecordId

合作夥伴系統裡來源紀錄的 id。

string
confidence

把握程度,由 0 至 1。

number
<= 1
missing

機械人沒有辨認這段事件,而由人或系統填上第一次保存的內容時為 true。同一事件 id 再送,仍保留第一次。

boolean
duplicate

合作夥伴把這列標成另一事件的重複時為 true。

boolean
annotated

第一次內容保存之後,有人補上細節時為 true。

boolean
operatorAction

操作員做了什麼。例子:take_over、clear_path。

string
guided

有人在這段事件中引導機械人時為 true。

boolean
repositioned

機械人被人手搬動,或被遙控移動時為 true。

boolean
reset

這段事件中機械人被重設時為 true。

boolean
consequence

事故或近距離接觸之後的結果。

string
Allowed values: none near_miss contact damage injury
obstacleClass

障礙物類別。例子:cart。

string
stopReason

機械人為何停下。例子:obstacle、estop。

string
rerouteAttempts

機械人改走另一條路的次數。

integer
recoveryType

機械人如何恢復。例子:reroute、wait。

string
contactOrNearContact

有接觸或近距離接觸時為 true。

boolean
incidentClass

事故類別。例子:collision。

string
injuryOrDamage

有人受傷或有物件損毀時為 true。

boolean
evidenceRef

指向合作夥伴所持證據的參考。YAS 不會去取。

string
resolution

這段事件如何結束。

string
Allowed values: recovered takeover unresolved aborted
version

變更後的軟件版本。

string
changeReason

軟件為何變更。

string
rollback

這次變更把軟件退回舊版時為 true。

boolean
mapOrConfigUpdate

這次變更更新了地圖或設定時為 true。

boolean
distanceM

與物件或人的距離,單位是米。這不是行走距離。

number
objectMotion

物件是靜止還是在移動。

string
Allowed values: static dynamic unknown
subject

附近的對象是不是人。

string
Allowed values: human non_human unknown
responseSeconds

由偵測到第一次動作的秒數。不知道就不要送這個欄位。不要送 null。

number

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"events": [
{
"robotId": "rbt_example",
"eventId": "evt_1001",
"eventStart": "2026-10-15T10:00:00.000Z",
"timezone": "Asia/Hong_Kong",
"type": "mode_change",
"nativeCode": "100",
"nativeDescription": "Autonomous moving"
}
]
}

事件已保存。accepted 是新存的列。duplicates 是該合作夥伴、機械人與事件 id 本來已有的列。eventIds 按順序列出每個 id。

Media typeapplication/json
object
accepted
required
integer
duplicates
required
integer
eventIds
required
Array<string>

Example

{
"accepted": 1,
"duplicates": 0,
"eventIds": [
"evt_1001"
]
}
400事件清單是空的,或缺必填欄位,或 `type`、`objectMotion`、`subject`、`resolution`、`consequence` 不在允許的值內。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "invalid_body"
}
401沒有 server key,或 server key 不正確。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "invalid_credentials"
}
403server key 可以只限車輛、只限機械人,或兩者都可以。超出範圍的呼叫是 403 `forbidden`,而且不會保存。`identity_mismatch` 表示 `partnerId` 與 server key 不符。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "forbidden"
}
404未知的 `robotId`。這次什麼都不會存。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "not_found"
}
413超過 500 筆事件。什麼都不會存。
Media typeapplication/json
object
error
required

穩定的錯誤代碼。沒有 stack trace。

string

Example

{
"error": "payload_too_large"
}