送出機械人事件(beta)
const url = 'https://api.example.yas/v1/robots/events';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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 等於事件筆數。
Authorizations
小節:AuthorizationsRequest Bodyrequired
小節:Request Bodyrequiredobject
合作夥伴 id。必須與 server key 相符。
這次內容的 schema 版本。例子:2026-11。
送出這次內容的系統名稱。例子:partner-export。
送出時的韌體版本。
合作夥伴的額外欄位。照送出的內容保存。
object
這次呼叫的事件。送 1 至 500 筆。
object
機械人 id。這台機械人必須已經存在。
合作夥伴的事件 id。同一合作夥伴、機械人與事件 id,保留第一次的內容。
這段事件開始的時間,ISO-8601。
IANA 時區。例子:Asia/Hong_Kong。
事件種類。
合作夥伴對這次事件的代碼。
nativeCode 的合作夥伴說明。
這次事件所屬的任務實例。沒有就可以不送。
場地 id。
場地內的區域 id。
這段事件結束的時間,ISO-8601。
這次內容最後更新的時間,ISO-8601。
這段事件的長度,單位是秒。這不是反應時間。
合作夥伴的原因代碼。
事件前的運作模式。
事件進行中的運作模式。
事件後的運作模式。
合作夥伴在這次事件上記下的任務狀態。
合作夥伴系統裡來源紀錄的 id。
把握程度,由 0 至 1。
機械人沒有辨認這段事件,而由人或系統填上第一次保存的內容時為 true。同一事件 id 再送,仍保留第一次。
合作夥伴把這列標成另一事件的重複時為 true。
第一次內容保存之後,有人補上細節時為 true。
操作員做了什麼。例子:take_over、clear_path。
有人在這段事件中引導機械人時為 true。
機械人被人手搬動,或被遙控移動時為 true。
這段事件中機械人被重設時為 true。
事故或近距離接觸之後的結果。
障礙物類別。例子:cart。
機械人為何停下。例子:obstacle、estop。
機械人改走另一條路的次數。
機械人如何恢復。例子:reroute、wait。
有接觸或近距離接觸時為 true。
事故類別。例子:collision。
有人受傷或有物件損毀時為 true。
指向合作夥伴所持證據的參考。YAS 不會去取。
這段事件如何結束。
變更後的軟件版本。
軟件為何變更。
這次變更把軟件退回舊版時為 true。
這次變更更新了地圖或設定時為 true。
與物件或人的距離,單位是米。這不是行走距離。
物件是靜止還是在移動。
附近的對象是不是人。
由偵測到第一次動作的秒數。不知道就不要送這個欄位。不要送 null。
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" } ]}Responses
小節:Responses200
小節:200事件已保存。accepted 是新存的列。duplicates 是該合作夥伴、機械人與事件 id 本來已有的列。eventIds 按順序列出每個 id。
object
Example
{ "accepted": 1, "duplicates": 0, "eventIds": [ "evt_1001" ]}400事件清單是空的,或缺必填欄位,或 `type`、`objectMotion`、`subject`、`resolution`、`consequence` 不在允許的值內。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "invalid_body"}401沒有 server key,或 server key 不正確。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "invalid_credentials"}403server key 可以只限車輛、只限機械人,或兩者都可以。超出範圍的呼叫是 403 `forbidden`,而且不會保存。`identity_mismatch` 表示 `partnerId` 與 server key 不符。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "forbidden"}404未知的 `robotId`。這次什麼都不會存。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "not_found"}413超過 500 筆事件。什麼都不會存。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "payload_too_large"}