업로드 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 Created
{
"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 Created
{
"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 type: “application/zip”)으로 POST합니다.
업로드 및 유효성 검사 결과를 확인하려면 상태 확인 URL을 사용합니다.
상태 확인
상태 확인 URL에 GET을 사용하면 업로드 성공 여부를 확인할 수 있습니다. 업로드 URL에 대한 POST가 완료된 후에도 서버의 내부 처리 및 유효성 검사에 시간이 걸릴 수 있습니다. 보통 이것은 몇 초 안에 완료됩니다. 상태 확인 URL은 여러 번 호출할 수 있습니다. 초당 한 번 정도 폴링하는 것이 좋습니다. 120초를 초과해도 완료되지 않는 경우 업로드 실패로 간주하여 상태 확인 엔드포인트 폴링을 중단합니다.
응답
{
"status": "...",
"reason": "..."
}
status:"VALIDATING","ERROR","COMPLETED"중 하나VALIDATING: 업로드 내용의 유효성 검사 중COMPLETED: 업로드 성공ERROR: 유효성 검사 오류 또는 어떤 이유로 업로드 실패
reason:status가"ERROR"일 경우 유효성 검사 오류에 대한 자세한 내용