開始使用
用後端的 server key 把機械人資料送到 YAS。先建立機械人。之後的呼叫都要這台機械人已存在。
PUT /v1/robots/{robotId}(beta) — 機械人主檔。先送一次,有改動再送。POST /v1/robots/maps(beta) — 地面格網或點雲。完成上傳。POST /v1/robots/events(beta) — 模式、告警、人工介入、導航、事故、任務狀態、軟件變更,或proximity(附近的人或物件)。POST /v1/robots/summaries/status(beta) — 每 1–5 秒。連線、移動、定位與位置。POST /v1/robots/summaries/components(beta) — 每 10–60 秒。電池、驅動、感知、四周情況。POST /v1/robots/tasks(beta) — 每個任務一筆。POST /v1/robots/maintenance(beta) — 每次維修一筆。
之後再送機械人、任務或維修,會蓋掉舊內容。要留的欄位請每次再送。已完成的地圖維持不變,直到下一次完成上傳成功。同一合作夥伴、機械人與事件 id 的事件,保留第一次。
狀態與部件紀錄沒有 id。同一時段再送,YAS 會多存一列。
xM、yM、zM 是地圖座標,單位是米。可以的話,先完成地圖,再送位置。就算這個 mapId 從未完成,狀態列仍會保存。
YAS 按 operatingMode 計時間:
- 在線只計明確的
idle、autonomous、manual或charging。不送這個欄位的時段,不算在線,也不算作業。 idle與charging是在線,不是作業。- 作業是
autonomous或manual。 moving另計,不會加進在線或作業時間。
附近的人或物件用 proximity。中斷,以及中斷怎樣結束,用其他事件類型。
欄位名稱與內容見各操作頁。
地圖上傳
小節:地圖上傳按地圖 operation 的 JSON 範例簽發 upload URL,以 Content-Type: application/octet-stream 將檔案 PUT 到回傳的 uploadUrl,然後以相同的 partnerId、robotId 與 mapId 呼叫 complete。JSON 的 contentType 描述地圖格式(occupancy_grid 或 point_cloud),與 HTTP 上傳 header 分開。
目前每檔最多 50 MiB,或較低的 Storage 設定上限。上傳憑證有效兩小時;須於簽發後 24 小時內 complete。位元組會先進入私人 Storage,complete 才核對實際大小。大小不符的檔案可能暫佔 Storage,但不會成為 ready。收到 422 invalid_media 時請重新簽發,不要覆寫物件。
簽發替換上傳不會影響目前可用的地圖;complete 成功才會取代。再次簽發同一地圖會取代未完成的上傳。請依序處理同一地圖的替換,並 complete 最新的一次。重複成功的 complete 只會回傳 ready,不改變地圖時間。
地圖上傳必須使用 byteLength 與 signed upload → complete 流程。含有 contentBase64 的請求會回傳 400 invalid_body,不支援 inline 地圖上傳。
API 執行區域
小節:API 執行區域呼叫 Supabase-hosted API 中較多資料庫操作的功能時,建議送 x-region: ap-southeast-1,讓執行區域靠近新加坡資料庫。可從回應的 x-sb-edge-region 核對。指定區域會停用自動跨區 failover;區域故障時須改動或移除該 header。此 header 只用於 API 呼叫,不用於回傳的 Storage URL 上傳。參閱 Supabase regional invocation。
