English

アップロード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-<ツール名>-<バージョン>” (e.g. “api-itemcreator-0.5”)

注: 開発者では無く、アップロード者のCCKアクセストークンを使うことに注意してください

クラフトアイテム

{
    "contentType": "application/zip",
    "fileName": "item_template.zip",
    "fileSize": 123456, // zipファイルのサイズ (bytes)
    "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/classes/ItemTemplateId.html で使うことができます。アップロードURLはuploadUrlに、ステータス確認URLはstatusApiUrlから得られます。

アクセサリー

{
    "contentType": "application/zip",
    "fileName": "accessory_template.zip",
    "fileSize": 123456, // zipファイルのサイズ (bytes)
}

レスポンス 正常時: 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"の場合、バリデーションエラーの詳細