大容量デジタルコンテンツのアップロード
ガチャに属するデジタルコンテンツは、マルチパートアップロードで分割して送れます。 各操作には対象ガチャへの書き込み権限が必要です。 画像用の公開アセットは対象外です。
手順
以下のパスには /admin/v2/gachas/{gacha_id}/assets を前置します。
すべてPOSTで、本文はJSONです。
| 操作 | 接尾辞 | 本文 | 成功応答 |
|---|---|---|---|
| 開始 | /begin_multipart_upload | original_name, content_type, data_size | 201: asset, upload_id |
| 分割URLの発行 | /issue_multipart_part_urls | asset_id, upload_id, part_count | 200: part_urls, expires_in_seconds |
| 完了 | /complete_multipart_upload | asset_id, upload_id, parts | 200: 実測サイズに更新した asset |
| 中止 | /abort_multipart_upload | asset_id, upload_id | 204: 本文なし |
開始時の data_size はバイト単位の申告値で、1から5GiBまでを受け付けます。
original_name は拡張子を含めます。
置き場所はサーバが決めるため、URLやS3のキーを渡す必要はありません。
URL発行後、part_urls の part_number に対応するファイル片を upload_url へPUTします。
各PUTの応答からETagを保存し、すべての送信後に完了操作へ渡します。
parts は [{ "part_number": 1, "etag": "..." }] の形です。
パート数と番号は1から10,000までで、番号の重複と空のETagは拒否します。
番号の順序は問いません。
最終パート以外は5MiB以上に分割してください（S3のパート制限）。
ファイル片は管理APIを経由せず、署名付きURLへ直接送ります。
管理APIの認証ヘッダーはPUTに付けません。
署名付きURLの有効期間は応答の expires_in_seconds で確認してください。
再送と中止
各操作に異なる Idempotency-Key を付け、同じ操作の同じ本文を再送するときは同じキーを使います。
成功応答の再取得には同じキーを使い、期限切れURLを再発行するときには新しいキーを使います。
キーを変えて開始すると別のアセットが作られます。
アップロードを取りやめるときは中止操作を呼びます。 S3での中止が成功した後にアセットの行も削除します。 完了済みのアップロードに中止操作を使わない でください。 完了操作の結果が不明な場合は、同じキーと本文で応答を確認してください。
他ガチャのアセットは404、書き込み権限不足は403、不正な入力は400です。
ストレージなどの想定外の失敗は500で、code は gacha_asset/multipart_upload_failed です。
内部のエラー詳細は応答に含めません。
開始、完了、中止の成功は監査ログに残ります。