跳到內容

送出機械人部件摘要(beta)

Beta
POST
/v1/robots/summaries/components
curl --request POST \
--url https://api.example.yas/v1/robots/summaries/components \
--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:01:00.000Z", "timezone": "Asia/Hong_Kong", "periodSeconds": 60, "socPct": 72, "peopleNearbyBand": "few" } ] }'

Beta。用 server key 送出 1 至 500 筆部件紀錄。每筆涵蓋 10 至 60 秒,要有 robotId、recordedAt、timezone 與 periodSeconds。電池、驅動、感知與四周情況欄位可省略。電流與溫度留在這次呼叫。每個致動器在 actuators 送一列,最多 32 列。只有一個驅動時,仍可用 motorCurrentA 與 motorTempC。只送分級與類別。不要送影像、聲音或人名。這台機械人必須已存在於這個 partnerId。未知的 robotId 是 404,這次什麼都不會存。清單是空的、缺欄位、periodSeconds 不在 10 至 60,或致動器超過 32 個,是 400。超過 500 筆是 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 至 500 筆。

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

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

string
recordedAt
required

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

string format: date-time
timezone
required

IANA 時區。例子:Asia/Hong_Kong。

string
periodSeconds
required

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

integer
>= 10 <= 60
socPct

電量,以百分比計。

number
voltageV

電池組電壓,單位是伏特。

number
currentA

電池組電流,單位是安培。

number
packTempC

電池組溫度,單位是攝氏。

number
chargePowerW

充電功率,單位是瓦。

number
cycleCount

充電循環次數。

integer
bmsWarning

電池警告文字。

string
motorCurrentA

驅動電流,單位是安培。多於一個驅動時請用 actuators。

number
motorTempC

驅動溫度,單位是攝氏。多於一個驅動時請用 actuators。

number
encoderError

編碼器報錯時為 true。

boolean
vibration

振動讀數,單位由合作夥伴自定。

number
lidarValid

這個時段的 lidar 數據有效時為 true。

boolean
cameraValid

這個時段的鏡頭數據有效時為 true。

boolean
localisationConfidence

定位信心,由 0 至 1。

number
<= 1
sensorCommsError

傳感器連線失敗時為 true。

boolean
surfaceClass

地面類別。例子:tile。

string
slopePct

斜度,以百分比計。

number
wetOrSlippery

地面潮濕或容易打滑時為 true。

boolean
lightingBand

光線。建議用 dark、dim、normal、bright。其他字也會保存。

string
tempC

氣溫,單位是攝氏。

number
humidityPct

相對濕度,以百分比計。

number
peopleNearbyBand

附近有多少人。建議用 none、few、many。其他字也會保存。

string
obstacleDensityBand

空間有多擠。建議用 clear、sparse、dense。其他字也會保存。

string
minClearanceM

最小淨空,單位是米。

number
actuators

每個致動器一列,最多 32 列。多於一個驅動時請用這個。

Array<object>
<= 32 items
object
name

致動器名稱。例子:drive_left、lift。

string
currentA

致動器電流,單位是安培。

number
tempC

致動器溫度,單位是攝氏。

number

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"records": [
{
"robotId": "rbt_example",
"recordedAt": "2026-10-15T10:01:00.000Z",
"timezone": "Asia/Hong_Kong",
"periodSeconds": 60,
"socPct": 72,
"peopleNearbyBand": "few"
}
]
}

部件紀錄已保存。accepted 等於紀錄筆數。

Media typeapplication/json
object
accepted
required
integer

Example

{
"accepted": 1
}
400紀錄清單是空的,或缺必填欄位,或 `periodSeconds` 不在 10 至 60,或 `actuators` 超過 32 項。
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"
}