跳到內容

簽發機械人地圖上傳(beta)

Beta
POST
/v1/robots/maps
curl --request POST \
--url https://api.example.yas/v1/robots/maps \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "robotId": "rbt_example", "mapId": "map_1", "mapVersion": "2026-10", "unitM": 1, "contentType": "occupancy_grid", "byteLength": 1048576 }'

Beta。用 server key 為一張地圖簽發網址。請送 partnerId、schemaVersion、sourceSystem、robotId、mapId、unitM、contentType 與 byteLength。機械人必須已存在於這個 partner。unitM 必須是 1。contentType 是 occupancy_grid 或 point_cloud;PUT 時請用 Content-Type: application/octet-stream。byteLength 是 1 至 52428800(50 MiB),或較低的 Storage 設定上限。同一 partnerId、robotId 與 mapId 再簽發,只會取代未完成的上傳;complete 成功前,使用中的地圖維持不變。被取代的 Storage 物件會在憑證失效後安全清理。contentSha256 與 pointCount 只會保存,不會驗證。

上傳憑證有效兩小時,expiresAt 是 ISO-8601 UTC 的憑證期限。須於簽發後 24 小時內 complete。上傳時位元組會先進入私人 Storage,complete 核對長度與類型後才成為 ready。Storage 不會把 signed URL 綁定到 byteLength;長度不符的檔案可能暫存,但不會成為 ready。上傳不可覆寫物件。內容不符時請重新簽發。每個 partner 的地圖與媒體合計最多 10 個未釋放的上傳預留,總額最多 1 GiB。每個預留按 bucket 的實際上限計算;放棄的上傳要等安全清理後才釋放。撤銷 Robots 權限會立即阻擋 mint 與 complete,但已簽發的 Storage 憑證可能仍可用至到期。未完成物件會在上傳憑證與 session 失效後清理;ready 媒體與目前使用中的地圖會保留。

不接受 contentBase64,會回傳 400 invalid_body。請送 byteLength,將位元組上傳到 signed URL,然後呼叫 complete。

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

地圖 id。再簽發只會換掉未完成的上傳。complete 成功後,目前使用的地圖才會更換。

string
unitM
required

地圖一個單位是一米。唯一允許的值是 1。

integer
Allowed values: 1
contentType
required

地圖格式:occupancy_grid 或 point_cloud。

string
Allowed values: occupancy_grid point_cloud
byteLength
required

實際上傳大小為 1 至 52428800 bytes,並受較低的 Storage 設定上限約束。Complete 時核對。

integer
>= 1 <= 52428800
mapVersion

跟這次上傳一起保存的版本標籤。目前使用的地圖維持不變,直到 complete。

string
originXM

地圖原點 X,單位是米。

number
originYM

地圖原點 Y,單位是米。

number
originZM

地圖原點 Z,單位是米。

number
contentSha256

即將上傳的位元組的 SHA-256。會保存,不會核對。

string
pointCount

合作夥伴報稱的點數。會保存,不會與位元組核對。

integer
firmwareVersion

送出時的韌體版本。

string
metadata

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

object
key
additional properties
any

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"robotId": "rbt_example",
"mapId": "map_1",
"mapVersion": "2026-10",
"unitM": 1,
"contentType": "occupancy_grid",
"byteLength": 1048576
}

已簽發上傳網址。Signed URL 有效兩小時,須於簽發後 24 小時內 complete。

Media typeapplication/json
object
robotId
required
string
mapId
required
string
uploadUrl
required

在 expiresAt 前把原始位元組 PUT 到此網址。私人物件要 complete 後才成為 ready。請勿分享或記錄此憑證。

string format: uri
objectKey
required

由 YAS 指定。請把位元組送到 uploadUrl。不要自行填這個值。

string
expiresAt
required

上傳憑證的 ISO-8601 UTC 到期時間,為簽發後兩小時。Complete 另有 24 小時期限。

string format: date-time
byteLength
required

宣告的 byteLength。Complete 會拒絕實際大小不符的物件。

integer

Example

{
"robotId": "rbt_example",
"mapId": "map_1",
"uploadUrl": "https://upload.example.yas/maps/map_1",
"objectKey": "partners/partner/robot/rbt_example/map/map_1/20261015T100000123Z",
"expiresAt": "2026-10-15T12:00:00.000Z",
"byteLength": 1048576
}
400缺少或錯誤的必填欄位、不支援的 content type,或送了 contentBase64。不會建立上傳。
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宣告大小超過實際 Storage 上限(最多 52428800 bytes)。
Media typeapplication/json
object
error
required

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

string

Example

{
"error": "payload_too_large"
}
429未釋放的上傳預留已達 partner 上限。清理釋放容量後再試。
Media typeapplication/json
object
error
required

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

string

Example

{
"error": "upload_quota_exceeded"
}
503Storage 或必要設定暫時無法使用。請按 Retry-After 指定時間重試。
Media typeapplication/json
object
error
required

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

string

Example

{
"error": "unavailable"
}