跳到內容

送出機械人任務(beta)

Beta
POST
/v1/robots/tasks
curl --request POST \
--url https://api.example.yas/v1/robots/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "robotId": "rbt_example", "taskInstanceId": "task_1001", "taskId": "patrol_12", "taskType": "patrol", "keywords": [ "shared_space", "night" ], "executeStart": "2026-10-15T10:00:00.000Z", "timezone": "Asia/Hong_Kong", "status": "complete" }'

Beta。用 server key 建立或取代一筆任務。請送 partnerId、schemaVersion、sourceSystem、robotId、taskInstanceId、executeStart 與 timezone。這台機械人必須已存在於這個 partnerId。未知的 robotId 是 404。之後用同一個 partnerId、robotId 與 taskInstanceId 再送,會蓋掉舊內容。選填欄位不送就會清掉。taskType 的例子是 patrol 與 charging。keywords 的例子是 shared_space、night 與 heavy_traffic。其他詞也會保存。不送 keywords 就會清掉。空清單不會保存任何詞。updatedAt 是 ISO-8601 UTC。

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

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

string
taskInstanceId
required

這次任務執行的 id。同一合作夥伴、機械人與任務實例再送,會蓋掉舊內容。

string
executeStart
required

任務開始的時間,ISO-8601。

string format: date-time
timezone
required

IANA 時區。例子:Asia/Hong_Kong。

string
taskId

合作夥伴的任務定義 id。例子:patrol_12。

string
taskType

機械人在做什麼。例子:patrol、charging。

string
keywords

描述這次任務的詞。YAS 日後用這些詞把相近的任務歸在一起。例子:shared_space、night、heavy_traffic。其他詞也會保存。

Array<string>
<= 32 items
executeEnd

任務結束的時間,ISO-8601。

string format: date-time
status

任務狀態。其他值會被拒絕。

string
Allowed values: planned running complete failed cancelled
closer

誰結束任務:robot、operator 或 partner。

string
Allowed values: robot operator partner
isArrived

機械人到達目標時為 true。

boolean
routeId

路線 id。

string
distanceM

這次任務的行走距離,單位是米。

number
durationSeconds

這次任務的時長,單位是秒。

number
startSoc

開始時的電量,以百分比計。

number
endSoc

結束時的電量,以百分比計。

number
interventionCount

這次任務中的人工介入次數。

integer
abnormalReason

任務為何異常。

string
siteId

場地 id。

string
sharedSpace

任務在與人共用的空間進行時為 true。

boolean
outcome

任務如何結束:complete、interrupted 或 aborted。

string
Allowed values: complete interrupted aborted
firmwareVersion

送出時的韌體版本。

string
metadata

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

object
key
additional properties
any

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"robotId": "rbt_example",
"taskInstanceId": "task_1001",
"taskId": "patrol_12",
"taskType": "patrol",
"keywords": [
"shared_space",
"night"
],
"executeStart": "2026-10-15T10:00:00.000Z",
"timezone": "Asia/Hong_Kong",
"status": "complete"
}

任務已保存。之後用同一個任務實例再送,會蓋掉它。updatedAt 是 ISO-8601 UTC。

Media typeapplication/json
object
robotId
required
string
taskInstanceId
required
string
updatedAt
required
string format: date-time

Example

{
"robotId": "rbt_example",
"taskInstanceId": "task_1001",
"updatedAt": "2026-10-15T10:45:00.000Z"
}
400缺少必填欄位,或 `status`、`closer`、`outcome` 不在允許的值內。
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"
}