送出機械人狀態摘要(beta)
const url = 'https://api.example.yas/v1/robots/summaries/status';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"partnerId":"partner","schemaVersion":"2026-11","sourceSystem":"partner-export","records":[{"robotId":"rbt_example","recordedAt":"2026-10-15T10:00:05.000Z","timezone":"Asia/Hong_Kong","periodSeconds":5,"cloudLink":"up","wifiRssiDbm":-62,"speedAvgMps":0.4}]}'};
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/summaries/status \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "records": [ { "robotId": "rbt_example", "recordedAt": "2026-10-15T10:00:05.000Z", "timezone": "Asia/Hong_Kong", "periodSeconds": 5, "cloudLink": "up", "wifiRssiDbm": -62, "speedAvgMps": 0.4 } ] }'Beta。用 server key 送出 1 至 1000 筆狀態紀錄。每筆涵蓋 1 至 5 秒,要有 robotId、recordedAt、timezone 與 periodSeconds。連線、移動與位置欄位可省略。xM、yM、zM 是地圖座標,單位是米。mapId 最好是已完成的地圖。地圖尚未完成,這筆仍會存。YAS 按 operatingMode 計在線與作業時間。只有明確的 idle、autonomous、manual 或 charging 才算在線。沒有送 operatingMode 的時段,不算在線,也不算作業。idle 與 charging 是在線,不是作業。作業時間是 autonomous 或 manual。moving 另計,不會加進這些時間。這台機械人必須已存在於這個 partnerId。未知的 robotId 是 404,這次什麼都不會存。清單是空的、缺欄位、periodSeconds 不在 1 至 5,或 operatingMode 不在允許的值內,是 400。超過 1000 筆是 413。這些紀錄沒有 id。同一時段再送,YAS 會多存一列。accepted 等於紀錄筆數。
Authorizations
小節:AuthorizationsRequest Bodyrequired
小節:Request Bodyrequiredobject
合作夥伴 id。必須與 server key 相符。
這次內容的 schema 版本。例子:2026-11。
送出這次內容的系統名稱。例子:partner-export。
送出時的韌體版本。
合作夥伴的額外欄位。照送出的內容保存。
object
這次呼叫的狀態時段。送 1 至 1000 筆。
object
機械人 id。這台機械人必須已經存在。
這個時段結束的時間,ISO-8601 UTC。
IANA 時區。例子:Asia/Hong_Kong。
這個時段的長度,單位是秒。允許範圍是 1 至 5。
這個時段內主電源正常時為 true。
控制器狀態。例子:ready。
這個時段的雲端連線。例子:up。
Wi-Fi 強度,單位是 dBm。
接入點或區域名稱。
來回延遲,單位是毫秒。
封包遺失,以百分比計。
這個時段內連線重新接上的次數。
機械人為何離線。operatingMode 是 offline 時請送。
這個時段的行走距離,單位是米。
平均速度,單位是米每秒。
這個時段內的最高速度,單位是米每秒。
定位質素,由 0 至 1。
這個位置所用的地圖。最好是已完成的地圖。地圖尚未完成,這筆仍會存。
地圖座標的 X。一個單位是一米。
地圖座標的 Y。一個單位是一米。
地圖座標的 Z。合作夥伴有高度時才送。一個單位是一米。
機械人當時如何運作。offline 不是在線。idle 與 charging 是在線,不是作業。autonomous 與 manual 是在線,也是作業。不送這個欄位的時段,不算在線,也不算作業。
這個時段內機械人在移動時為 true。這與 operatingMode 分開,不會加進在線或作業時間。
機械人當時在與人共用的空間時為 true。
Example
{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "records": [ { "robotId": "rbt_example", "recordedAt": "2026-10-15T10:00:05.000Z", "timezone": "Asia/Hong_Kong", "periodSeconds": 5, "cloudLink": "up", "wifiRssiDbm": -62, "speedAvgMps": 0.4 } ]}Responses
小節:Responses200
小節:200狀態紀錄已保存。accepted 等於紀錄筆數。
object
Example
{ "accepted": 1}400紀錄清單是空的,或缺必填欄位,或 `periodSeconds` 不在 1 至 5,或 `operatingMode` 不在允許的值內。
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超過 1000 筆紀錄。什麼都不會存。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "payload_too_large"}