簽發機械人地圖上傳(beta)
const url = 'https://api.example.yas/v1/robots/maps';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"partnerId":"partner","schemaVersion":"2026-11","sourceSystem":"partner-export","robotId":"rbt_example","mapId":"map_1","mapVersion":"2026-10","unitM":1,"contentType":"occupancy_grid","byteLength":1048576}'};
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/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。
Authorizations
小節:AuthorizationsRequest Bodyrequired
小節:Request Bodyrequiredobject
合作夥伴 id。必須與 server key 相符。
這次內容的 schema 版本。例子:2026-11。
送出這次內容的系統名稱。例子:partner-export。
機械人 id。這台機械人必須已經存在。
地圖 id。再簽發只會換掉未完成的上傳。complete 成功後,目前使用的地圖才會更換。
地圖一個單位是一米。唯一允許的值是 1。
地圖格式:occupancy_grid 或 point_cloud。
實際上傳大小為 1 至 52428800 bytes,並受較低的 Storage 設定上限約束。Complete 時核對。
跟這次上傳一起保存的版本標籤。目前使用的地圖維持不變,直到 complete。
地圖原點 X,單位是米。
地圖原點 Y,單位是米。
地圖原點 Z,單位是米。
即將上傳的位元組的 SHA-256。會保存,不會核對。
合作夥伴報稱的點數。會保存,不會與位元組核對。
送出時的韌體版本。
合作夥伴的額外欄位。照送出的內容保存。
object
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}Responses
小節:Responses200
小節:200已簽發上傳網址。Signed URL 有效兩小時,須於簽發後 24 小時內 complete。
object
在 expiresAt 前把原始位元組 PUT 到此網址。私人物件要 complete 後才成為 ready。請勿分享或記錄此憑證。
由 YAS 指定。請把位元組送到 uploadUrl。不要自行填這個值。
上傳憑證的 ISO-8601 UTC 到期時間,為簽發後兩小時。Complete 另有 24 小時期限。
宣告的 byteLength。Complete 會拒絕實際大小不符的物件。
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。不會建立上傳。
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宣告大小超過實際 Storage 上限(最多 52428800 bytes)。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "payload_too_large"}429未釋放的上傳預留已達 partner 上限。清理釋放容量後再試。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "upload_quota_exceeded"}503Storage 或必要設定暫時無法使用。請按 Retry-After 指定時間重試。
object
穩定的錯誤代碼。沒有 stack trace。
Example
{ "error": "unavailable"}