REST API 參考

API 資訊

屬性	值
版本	v1.0
Base URL	http://localhost:65530/api
Content-Type	application/json
認證	無需認證

資料模型

Task

地圖畫建造任務物件

欄位	類型	必填	描述
Group	string	✓	群組名稱
Type	string	✓	任務類型，固定為 "mapArt"
ID	string	✓	任務唯一識別碼
Status	enum	✓	任務狀態：init, building, done, error, pause
Record	TaskRecord		建造記錄
BlueprintPath	string	✓	地圖畫檔案路徑
OffsetX	number	✓	X 軸偏移量
OffsetY	number	✓	Y 軸偏移量
OffsetZ	number	✓	Z 軸偏移量
MaterialServer	number	✓	材料伺服器編號
BuildingServer	number	✓	建造伺服器編號
MaterialWarpPoint	string		材料傳送點名稱
BuildingWarpPoint	string		建造傳送點名稱
IsDestroy	boolean		是否為破壞模式
InitialTime	string		初始化時間 (ISO 8601)

TaskRecord

任務執行記錄

欄位	類型	必填	描述
TotalBlocks	number		總方塊數
RemainBlocks	number		剩餘方塊數
StartTime	string		開始時間 (ISO 8601)
FinishTime	string		完成時間 (ISO 8601)
Finish	boolean		是否完成
BuildScopes	BuildScope[]		建造時間範圍
StopTimes	number		停止次數
TakeMaterialTimes	number		取材次數
PlaceBlockTimes	number		放置方塊次數
TakeMaterialTime	number		取材耗時 (納秒)
PreviewImage	string[]		預覽圖片 (Base64)
Width	number		寬度
Height	number		高度
ErrorMessage	string		錯誤訊息
Materials	any[]		材料清單

BuildScope

建造時間範圍

欄位	類型	必填	描述
StartTime	string	✓	開始時間 (ISO 8601)
EndTime	string	✓	結束時間 (ISO 8601)

Map

地圖物件

欄位	類型	必填	描述
uuid	string	✓	地圖唯一識別碼
id	number	✓	地圖 ID 編號
rename	boolean		是否啟用重新命名
name	string		當前地圖名稱
skip	boolean		是否跳過此地圖
origin_name	string		原始地圖名稱
copy	boolean		是否複製此地圖
copy_count	number		複製數量

ItemData

物品資料

欄位	類型	必填	描述
id	number	✓	物品 ID 編號
translate_name	string	✓	翻譯後名稱
name	string	✓	英文原名稱
stack_size	number	✓	堆疊上限

API 端點

系統管理

GET /test

檢查 Bot 客戶端連線狀態

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 已連接 "not ok" - 未連接

GET /user/name

取得當前 Bot 客戶端名稱

回應

狀態碼	內容類型	描述
200	text/plain	Bot 客戶端名稱

POST /exit

安全退出 Nullbot Mapart 程式

回應

狀態碼	描述
200	退出流程已觸發

POST /profile

執行系統效能分析

回應

狀態碼	內容類型	描述
200	text/plain	"Profile finished" - 分析完成
201	text/plain	"Profile is already running" - 已在執行中
500	text/plain	分析失敗錯誤訊息

GET /auth

取得 GMM 驗證資訊

回應

狀態碼	內容類型	Schema
200	application/json	{"Code": string, "RedirectUri": string}

GET /tunnel-auth

隧道服務驗證端點

配置管理

GET /config/{service}

取得服務配置

路徑參數

參數	類型	必填	描述
service	string	✓	服務名稱

回應

狀態碼	內容類型	描述
200	application/json	服務配置物件
404		服務不存在

POST /config/{service}

更新服務配置

路徑參數

參數	類型	必填	描述
service	string	✓	服務名稱

請求體

內容類型	Schema
application/json	配置物件

回應

狀態碼	描述
200	配置更新成功
400	請求參數錯誤
404	服務不存在

地圖畫建造

GET /mapart/tasks

取得所有建造任務

回應

狀態碼	內容類型	Schema
200	application/json	Task[]

POST /mapart/tasks

建立建造任務

請求體

內容類型	Schema
application/json	Task | Task[]

回應

狀態碼	內容類型	描述
200	text/plain	任務 ID (多任務以逗號分隔)
400	text/plain	參數錯誤或座標未對齊
500	text/plain	伺服器內部錯誤

GET /mapart/tasks/{id}

取得特定任務

路徑參數

參數	類型	必填	描述
id	string	✓	任務 ID

回應

狀態碼	內容類型	Schema
200	application/json	Task
404		任務不存在

PUT /mapart/tasks/{id}

更新任務

路徑參數

參數	類型	必填	描述
id	string	✓	任務 ID

請求體

內容類型	Schema
application/json	Task

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 更新成功
400	text/plain	參數錯誤或任務未初始化
404		任務不存在
500	text/plain	伺服器內部錯誤

DELETE /mapart/tasks/{id}

刪除任務

路徑參數

參數	類型	必填	描述
id	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 刪除成功
404		任務不存在
500	text/plain	伺服器內部錯誤

DELETE /mapart/tasks/batch

批次刪除任務

請求體

內容類型	Schema
application/json	string[]

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 全部刪除成功
207	application/json	部分成功的詳細狀態
400	text/plain	請求參數錯誤
404		所有任務都不存在

POST /mapart/build/{id}

開始建造

路徑參數

參數	類型	必填	描述
id	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 建造開始成功
400	text/plain	任務已在執行中
404		任務不存在
500	text/plain	伺服器內部錯誤

POST /mapart/rebuild/{id}

重新建造

路徑參數

參數	類型	必填	描述
id	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 重新建造設定成功
404		歷史任務不存在
500	text/plain	伺服器內部錯誤

POST /mapart/stop

停止建造

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 停止成功
400	text/plain	無進行中的任務

POST /mapart/order

任務排序

請求體

內容類型	Schema
application/json	{"type": string, "source": number, "destination": number}

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 排序成功
400	text/plain	參數錯誤或類型無效
500	text/plain	伺服器內部錯誤

GET /mapart/task/autoBuild

取得自動建造狀態

回應

狀態碼	內容類型	Schema
200	application/json	boolean

POST /mapart/task/autoBuild

設定自動建造

查詢參數

參數	類型	必填	描述
auto	string	✓	"true" 或 "false"

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	缺少 auto 參數

GET /mapart/history

取得建造歷史

回應

狀態碼	內容類型	Schema
200	application/json	Task[]

GET /preview/{id}

取得任務預覽圖片

路徑參數

參數	類型	必填	描述
id	string	✓	任務 ID

回應

狀態碼	內容類型	描述
200	image/png	預覽圖片
404		任務不存在

GET /render

渲染當前建造任務

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 渲染成功
400	text/plain	無進行中的任務
500	text/plain	渲染或檔案儲存錯誤

後處理操作

POST /postProcessing/scan

掃描地圖

請求體

內容類型	Schema
application/json	{"Start": string, "Width": number, "Height": number, "Order": string, "Template": string, "CopyAmount": number}

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 掃描任務開始
400	text/plain	參數錯誤或任務鎖定

GET /postProcessing/maps

取得地圖列表

回應

狀態碼	內容類型	Schema
200	application/json	Map[]

GET /postProcessing/map/{id}

取得特定地圖資訊

路徑參數

參數	類型	必填	描述
id	string	✓	地圖 ID

回應

狀態碼	內容類型	Schema
200	application/json	{"MapID": number, "Locked": boolean}
400	text/plain	地圖 ID 格式錯誤
404		地圖不存在

GET /postProcessing/map/{id}/image

取得地圖圖片

路徑參數

參數	類型	必填	描述
id	string	✓	地圖 ID

回應

狀態碼	內容類型	描述
200	image/png	128x128 PNG 圖片
400	text/plain	地圖 ID 格式錯誤
404		地圖不存在
500	text/plain	圖片編碼錯誤

POST /postProcessing/map/clear

清除地圖快取

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 清除成功
400	text/plain	任務已鎖定或清除失敗

POST /postProcessing

設定複製參數

請求體

內容類型	Schema
application/json	{"Start": string, "Width": number, "Height": number, "Order": string, "Template": string, "CopyAmount": number}

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

POST /postProcessing/size

設定複製尺寸

查詢參數

參數	類型	必填	描述
width	number	✓	寬度
height	number	✓	高度

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

POST /postProcessing/copyAmount

設定複製數量

查詢參數

參數	類型	必填	描述
amount	number	✓	複製數量

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

POST /postProcessing/copy

開始複製

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 複製任務開始
400	text/plain	任務已鎖定

POST /postProcessing/copy/{uuid}

設定特定地圖複製

路徑參數

參數	類型	必填	描述
uuid	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
copy	boolean	✓	是否複製

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

POST /postProcessing/copyCount/{uuid}

設定複製計數

路徑參數

參數	類型	必填	描述
uuid	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
count	number	✓	複製數量

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

POST /postProcessing/setRename

設定重新命名參數

請求體

內容類型	Schema
application/json	[{"uuid": string, "rename": boolean}]

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	請求體錯誤或任務鎖定

POST /postProcessing/rename

開始重新命名

查詢參數

參數	類型	必填	描述
mode	string		重新命名模式 (預設: loose)

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 重新命名任務開始
400	text/plain	任務已鎖定

POST /postProcessing/template

設定命名範本

查詢參數

參數	類型	必填	描述
template	string	✓	命名範本字串

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

GET /postProcessing/template/docs

取得範本文檔

回應

狀態碼	內容類型	Schema
200	application/json	[{"Type": string, "Name": string, "Description": string, "Example": string}]

POST /postProcessing/name/{uuid}

設定地圖名稱

路徑參數

參數	類型	必填	描述
uuid	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
name	string	✓	新的地圖名稱

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤、名稱太長或任務鎖定

POST /postProcessing/order

設定排序

查詢參數

參數	類型	必填	描述
order	string	✓	排序方式

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

POST /postProcessing/skip/{uuid}

跳過地圖

路徑參數

參數	類型	必填	描述
uuid	string	✓	地圖 UUID

查詢參數

參數	類型	必填	描述
skip	boolean	✓	是否跳過

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 設定成功
400	text/plain	參數錯誤或任務鎖定

POST /postProcessing/stop

停止後處理

回應

狀態碼	內容類型	描述
200	text/plain	"ok" - 停止成功

背景圖片管理

GET /background

取得背景圖片

回應

狀態碼	內容類型	描述
200	原始 MIME 類型	當前背景圖片
404		未設定背景圖片
500	text/plain	伺服器錯誤

回應標頭

• ETag: 快取標識

GET /background/list

取得背景列表

回應

狀態碼	內容類型	Schema
200	application/json	string[]

POST /background/upload

上傳背景圖片

請求體

內容類型	Schema
multipart/form-data	background: File

回應

狀態碼	內容類型	描述
200	text/plain	圖片雜湊值
400	text/plain	未找到檔案
415	text/plain	檔案不是圖片格式
500	text/plain	伺服器錯誤

POST /background/set

設定背景

查詢參數

參數	類型	必填	描述
hash	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	text/plain	"OK" - 設定成功
404		背景圖片不存在
500	text/plain	伺服器錯誤

POST /background/set/{hash}

設定特定背景

路徑參數

參數	類型	必填	描述
hash	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	text/plain	"OK" - 設定成功
404		背景圖片不存在
500	text/plain	伺服器錯誤

GET /background/hash

取得背景雜湊

回應

狀態碼	內容類型	描述
200	text/plain	當前背景雜湊值
404		未設定背景

GET /background/{hash}

取得背景圖片

路徑參數

參數	類型	必填	描述
hash	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	原始 MIME 類型	圖片檔案
404		背景圖片不存在
500	text/plain	伺服器錯誤

回應標頭

• Cache-Control: max-age=31536000

GET /background/thumbnail/{hash}

取得背景縮圖

路徑參數

參數	類型	必填	描述
hash	string	✓	背景圖片雜湊值

回應

狀態碼	內容類型	描述
200	image/jpg	JPG 縮圖
404		背景圖片不存在
500	text/plain	伺服器錯誤

回應標頭

• Cache-Control: max-age=31536000

GET /background/position

取得背景位置

回應

狀態碼	內容類型	Schema
200	application/json	number
404		未設定背景或背景不存在
500	text/plain	伺服器錯誤

POST /background/position

設定背景位置

查詢參數

參數	類型	必填	描述
position	number	✓	背景位置數值

回應

狀態碼	內容類型	描述
200	text/plain	"OK" - 設定成功
404		未設定背景或背景不存在
500	text/plain	伺服器錯誤

資料查詢

GET /data/items

取得物品列表

回應

狀態碼	內容類型	Schema
200	application/json	ItemData[]

GET /data/items/maxDamage

取得物品最大耐久度

回應

狀態碼	內容類型	Schema
200	application/json	{[itemId: string]: number}

GET /assets/items

取得物品圖示

查詢參數

參數	類型	必填	描述
id	number	✓	物品 ID

回應

狀態碼	內容類型	描述
200	image/png	物品圖示 PNG
404		物品 ID 不存在或圖示檔案不存在
500	text/plain	檔案讀取錯誤

回應標頭

• Cache-Control: max-age=86400

GET /header

頭像渲染

查詢參數

參數	類型	必填	描述
key	string	*	玩家名稱 (與 url 二擇一)
url	string	*	皮膚貼圖網址 (與 key 二擇一)
size	number		圖片尺寸 (預設: 512)
overlay	boolean		是否渲染第二層皮膚 (預設: true)
projection	string		投影方式: frontal 或 isometric (預設: isometric)

回應

狀態碼	內容類型	描述
200	image/png	渲染後的頭像 PNG
304		未修改 (基於 ETag)
400	text/plain	參數錯誤、皮膚獲取失敗或非法貼圖服務
5000	text/plain	渲染錯誤
5001	text/plain	圖片編碼錯誤

回應標頭

• ETag: 快取標識
• Cache-Control: max-age=86400

狀態碼

狀態碼	說明
200	請求成功
201	已創建
207	多狀態回應 (部分成功)
304	未修改 (快取有效)
400	請求參數錯誤
401	未授權
404	資源不存在
415	不支援的媒體類型
500	伺服器內部錯誤
5000	自訂錯誤：渲染失敗
5001	自訂錯誤：編碼失敗