上傳API
上傳 API 是一個 HTTP API，可讓您上傳工藝品和配件。
透過呼叫上傳啟動接口，您可以獲得上傳執行URL和狀態確認URL。透過依序呼叫所取得的URL，您可以上傳PITM資料和縮圖並檢查驗證結果。
範例程式碼 (Python) 包含這些進程的包裝器。
https://github.com/ClusterVR/PITMSample/blob/main/python/cluster_api.py
上傳文件
上傳 API 將 PITM 資料和縮圖作為單一 zip 檔案接收。
僅將以下兩個檔案放入 zip 檔案的“/”中。
對於工藝品
item_template.glb：工藝物品（PITM 資料格式）icon.png：縮圖（512px x 512px 不透明 PNG）
對於配件
accessory_template.glb：配件（PITM 資料格式）icon.png：縮圖（512px x 512px 不透明 PNG）
上傳起始端點
POST https://api.cluster.mu/v1/upload/item_template/policies（工藝物品）
POST https://api.cluster.mu/v1/upload/accessory_template/policies（配件）
通知開始上傳並取得文件本身的上傳URL和狀態確認URL。
請在 HTTP 標頭中設定以下內容。
- Content-Type: “application/json”
- X-Cluster-Access-Token：上傳者的 CCK 存取權令牌
- X-Cluster-App-Version: “2.0.0”
- X-Cluster-Device: “ClusterCreatorKit”
- X-Cluster-Platform: “ClusterCreatorKit”
- X-Cluster-Platform-Version：「api-<工具名稱>-<版本>」（例如「api-itemcreator-0.5」）
注意：請小心使用上傳者的 CCK 存取權令牌，而不是開發人員的。
工藝品
{
"contentType": "application/zip",
"fileName": "item_template.zip",
"fileSize": 123456, // zip 檔案的大小 (字節)
"isBeta": false // 如果作為測試版上傳則為 true，作為正式版上傳則為 false
}
回覆 正常：201 創建
{
"form": {...}, // 上傳URL使用的資料
"itemTemplateID": "12345678-abcd-1234-abcd-12345678abcd", // 新發放的ID
"uploadUrl": "https://file-storage.cluster.mu/xxxxxx",
"statusApiUrl": "https://upload-status.cluster.mu/item_template/xxxxxxxxxxxxxx"
}
此處取得的 itemTemplateID 可以在 https://docs.cluster.mu/script/en/classes/ItemTemplateId.html 中使用。上傳URL可以從 uploadUrl 取得，狀態確認URL可以從 statusApiUrl 取得。
配件
{
"contentType": "application/zip",
"fileName": "accessory_template.zip",
"fileSize": 123456, // zip 檔案的大小 (字節)
}
回覆 正常：201 創建
{
"form": {...}, // 上傳URL使用的資料
"accessoryTemplateID": "12345678-abcd-1234-abcd-12345678abcd", // 新發放的ID
"uploadUrl": "https://file-storage.cluster.mu/xxxxxx",
"statusApiUrl": "https://upload-status.cluster.mu/accessory_template/xxxxxxxxxxxxxx"
}
上傳URL可以從 uploadUrl 取得，狀態確認URL可以從 statusApiUrl 取得。
上傳
透過對上傳 URL 執行“POST”，您將實際上傳文件並開始驗證。發出的上傳 URL 呼叫僅允許一次。
將 form 的內容發佈為 HTTP 表單，並將 zip 檔案發佈為 item.zip（MIME 類型：「application/zip」）。
使用狀態確認 URL 檢查上傳和驗證結果。
檢查狀態
您可以透過對狀態確認 URL 執行 GET 來檢查上傳是否成功。即使在完成上傳 URL 的 POST 後，伺服器的內部處理和驗證可能需要一些時間。這通常需要幾秒鐘。狀態確認URL可以被多次呼叫。建議每秒輪詢一次。如果在 120 秒內未完成，則視為上傳失敗並停止輪詢狀態確認端點。
回覆
{
"status": "...",
"reason": "..."
}
status:"VALIDATING","ERROR","COMPLETED"之一VALIDATING：驗證上傳的內容COMPLETED: 上傳成功ERROR：因為某些原因導致驗證錯誤或上傳失敗
reason: 如果status為"ERROR"，則驗證錯誤的詳細訊息