跳到內容

送出機械人狀態摘要(beta)

Beta
POST
/v1/robots/summaries/status
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 等於紀錄筆數。

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
records
required

這次呼叫的狀態時段。送 1 至 1000 筆。

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

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

string
recordedAt
required

這個時段結束的時間,ISO-8601 UTC。

string format: date-time
timezone
required

IANA 時區。例子:Asia/Hong_Kong。

string
periodSeconds
required

這個時段的長度,單位是秒。允許範圍是 1 至 5。

integer
>= 1 <= 5
powerOk

這個時段內主電源正常時為 true。

boolean
controllerState

控制器狀態。例子:ready。

string
cloudLink

這個時段的雲端連線。例子:up。

string
wifiRssiDbm

Wi-Fi 強度,單位是 dBm。

number
accessPointOrZone

接入點或區域名稱。

string
latencyMs

來回延遲,單位是毫秒。

number
packetLossPct

封包遺失,以百分比計。

number
reconnectCount

這個時段內連線重新接上的次數。

integer
offlineReason

機械人為何離線。operatingMode 是 offline 時請送。

string
distanceM

這個時段的行走距離,單位是米。

number
speedAvgMps

平均速度,單位是米每秒。

number
speedMaxMps

這個時段內的最高速度,單位是米每秒。

number
localisationQuality

定位質素,由 0 至 1。

number
<= 1
mapId

這個位置所用的地圖。最好是已完成的地圖。地圖尚未完成,這筆仍會存。

string
xM

地圖座標的 X。一個單位是一米。

number
yM

地圖座標的 Y。一個單位是一米。

number
zM

地圖座標的 Z。合作夥伴有高度時才送。一個單位是一米。

number
operatingMode

機械人當時如何運作。offline 不是在線。idle 與 charging 是在線,不是作業。autonomous 與 manual 是在線,也是作業。不送這個欄位的時段,不算在線,也不算作業。

string
Allowed values: offline idle autonomous manual charging
moving

這個時段內機械人在移動時為 true。這與 operatingMode 分開,不會加進在線或作業時間。

boolean
sharedSpace

機械人當時在與人共用的空間時為 true。

boolean

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
}
]
}

狀態紀錄已保存。accepted 等於紀錄筆數。

Media typeapplication/json
object
accepted
required
integer

Example

{
"accepted": 1
}
400紀錄清單是空的,或缺必填欄位,或 `periodSeconds` 不在 1 至 5,或 `operatingMode` 不在允許的值內。
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超過 1000 筆紀錄。什麼都不會存。
Media typeapplication/json
object
error
required

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

string

Example

{
"error": "payload_too_large"
}