Multipart Upload

マルチパートアップロード機能は、ファイルを特定サイズのデータチャンクに分割し、それぞれのデータチャンクをサーバー側に個別にアップロードした後、全てのチャンクのアップロードが完了した時点でサーバー側で一つのリソースファイルにマージします。

主な制約事項:
1. 戻り値の仕組み: マルチパートアップロードはreturnBodyモードのみをサポートし、returnUrlモードはサポートしていません。
2. ファイル名の指定必須: ファイルのキーは必ず指定する必要があります（アップロードポリシーまたはリクエストヘッダで設定可能で、アップロードポリシーが優先されます）。
3. ドメインタイプ: オブジェクトストレージで提供されるアップロードドメインは通常ドメインです。

主要概念

マルチパートアップロードは2層構造を導入します。

1. ブロック（Block）： リソースの構成単位
2. チャンク（Chunk）： ブロック内の構成単位
   

注記: オブジェクトストレージのサーバー側は、アップロード後にファイルへ統合されていないブロックやチャンクを定期的（月に1回程度）でクリーンアップします。

基本フロー

マルチパートアップロードに関連するAPIには、ブロック作成（mkblk）、チャンクアップロード（bput）、ファイル作成（mkfile）が含まれます。アップロードプロセスの全体像は下図のとおりです。

ポイントは次の通りです：

• アップロード対象ファイルを、設定されたブロックサイズ（例：4MB）ごとに複数のブロックに分割します。最後のブロックは実際のファイルサイズに基づきます。ファイルが設定されたブロックサイズ未満の場合はブロックは1つだけです。
• ブロックサイズは4MBの倍数（例：4MB、8MB、12MBなど）でなければなりません。それ以外の場合、ファイルのETag値の計算に影響があります。
• 各ブロックをさらに事前定義されたチャンクサイズで分割し、mkblkでサーバー側にブロックを作成後、bputで残りのチャンクを逐次アップロードし、1つのブロックのアップロードを完了します。
• すべてのブロックのアップロードが完了したら、mkfileでこれらのブロック情報を指定順にマージして、マルチパートアップロード全体を完了します。

途中からの再開（レジュームアップロード）

マルチパートアップロード機能を利用すると、途中からのレジュームアップロードを実現できます。

マルチパートアップロード中に各チャンクが正常にアップロードされるたびに、クライアントはこれまでにアップロードが済んだチャンク数など進捗情報をサーバーから受け取ります。これにより、次にアップロードすべきチャンクが分かります。アップロード済みのチャンクは恒久的にサーバーに保存されませんが、この仕組みでレジュームが可能です。
レジュームアップロードを実装するには、クライアントで取得した進捗情報をローカルに毎回永続化する必要があります。これにより、プログラムの異常終了や再起動時にも、アップロードの続きから再開できます。
この仕組みを利用してファイルごとにアップロードの一時停止・再開ができます。

並行アップロード（同時アップロード）

マルチパートアップロード中、各ブロック内のチャンクは逐次アップロードですが、ブロック間は独立しています。そのため、複数のブロックを同時にアップロードすることが可能です。これにより、並行アップロードが実現できます。

ブロック作成 (Create Block)

新しいブロックを作成し、同時に最初のチャンクデータをアップロードします。

リクエスト説明

POST /mkblk/<blockSize>/<blockOrder>
    Host: <UploadDomain>
    Authorization:<UploadToken>
    Content-Length:<firstChunkSize>
    Content-Type:application/octet-stream
    UploadBatch:<uuid>
    Key:<key>
    <firstChunkBinary>

ヘッダー説明

パラメーター	必須	説明
Host	はい	Upload Domain Name。コンソールのOverview画面で取得可能。
Authorization	はい	Upload Credential
Content-Length	はい	最初のチャンクのコンテンツ長（バイト単位）
Content-Type	はい	固定値 application/octet-stream
UploadBatch	はい	マルチパートアップロードのタスクID（UUID形式ランダム文字列）。異なるファイルには異なるIDを使用。1つのタスクで同じUploadBatchを必ず使用
Key	いいえ	Custom File Name。URL-Safe Base64 Encoded必須

パラメーター説明

パラメーター	必須	説明
<blockSize>	はい	ブロックサイズ。4MBの倍数（4MB、8MB、12MBなど）。最後のブロックは実サイズ。単位: バイト
<blockOrder>	はい	ブロック番号。0から開始

リクエスト内容

最初のチャンクのバイナリ内容。

レスポンス説明

• 成功時：下記のJSON文字列を返します。

{
    "ctx":          "<Ctx           string>", 
    "checksum":     "<Checksum      string>",
    "crc32":         "<Crc32         int64>",
    "offset":        "<Offset        int64>"
}

フィールド	必須	説明
ctx	はい	このアップロード成功時に作成されたブロック単位のアップロード管理情報。以降のチャンクアップロード・ファイル生成の際に利用します。これは不透明フィールドであり、CDNetworks Object Storageサーバーのみが内容を解釈します。アップロード側で内容を変更しないでください。毎回返される <ctx> は、直後にアップロードされる次のチャンクと必ず対応します。不一致なチャンクのアップロード時は401エラーが返されます。
checksum	はい	アップロードブロックの検証コード。
crc32	はい	アップロードブロックのCrc32値。整合性検証に利用可能。
offset	はい	分割ブロック内での次アップロードチャンクのオフセット。

• 失敗時：下記のJSON文字列を返します。

{
    "code":     "<code string>",
    "message":  "<message string>"
}

フィールド	必須	説明
code	はい	HTTPレスポンスコード。HTTP Response Status Code 参照
message	はい	メッセージ内容

実例

curl -v -X POST --data-binary "@/home/test/0" -H "Authorization:86622e227a50d49d858c2494a935bc2e4ac543a7:ZTIzYjFiZmFkYWRjODdiNjJlMTI4NDgyZGI1MGJmMWYzZGE2MjllNA==:eyJzY29wZSI6ImltYWdlczpzbGljZS50eHQiLCJkZWFkbGluZSI6IjE0Mzg1ODg0MDYxMDkiLCJvdmVyd3JpdGUiOjAsImZzaXplTGltaXQiOjEwNzM3NDE4MjQsImluc3RhbnQiOjB9" -H "Content-Type:application/octet-stream" -H "Content-Length:4194304" -H "UploadBatch:abcdabcd-abcd-abcd-abcd-abcdabcdabcd"--url "http://uploadDomain/mkblk/4194304/0"

---

チャンクのアップロード（Upload Chunk）

指定ブロックのチャンクデータをアップロードします。チャンクサイズは環境に応じて調整可能です。同じブロック下にあるチャンクは必ず連続してアップロードされる必要があります。

リクエスト内容

POST /bput/<ctx>/<nextChunkOffset>
    Host: <UploadDomain>
    Authorization:<UploadToken>
    Content-Length:<ChunkSize>
    Content-Type:application/octet-stream
    UploadBatch:<uuid>
    Key:<key>
    <ChunkBinary>

ヘッダー説明

パラメーター	必須	説明
Host	はい	Upload Domain Name。コンソールのOverview画面で取得可能。
Authorization	はい	Upload Credential
Content-Length	はい	チャンクの長さ（バイト単位）
Content-Type	はい	固定値 application/octet-stream
UploadBatch	はい	マルチパートアップロードタスクID（UUID）。同一タスクには同一IDを使用します。
Key	いいえ	Custom File Name。URL-Safe Base64 Encoded形式が条件です。

パラメーター説明

パラメータ	必須	説明
<ctx>	はい	直前のアップロードから返されたブロックレベルの制御情報
<nextChunkOffset>	はい	ブロック内で現チャンクの開始オフセット位置

リクエスト内容

現チャンクのバイナリデータ

<ChunkBinary>

レスポンス説明

• 成功した場合、次の内容のJSONが返されます。

{
        "ctx":          "<Ctx           string>", 
        "checksum":     "<Checksum      string>",
        "crc32":         "<Crc32         int64>",
        "offset":        "<Offset        int64>"
}

フィールド名	必須	説明
ctx	はい	このアップロード成功時のブロック単位制御情報。以降のチャンクアップロード・ファイル生成時に使用。CDNetworks Object Storageサーバー側のみ解釈可能。不一致なデータをアップロードすると401エラーを返します。
checksum	はい	アップロードブロック用の検証コード。
crc32	はい	ブロックのCrc32。アップロード整合性検証に利用可能。
offset	はい	分割ブロック内の次のチャンクオフセット

• 失敗時は、以下のようなJSONが返却されます。

{
        "code":     "<code string>",
        "message":  "<ErrMsg string>"
}

フィールド名	必須	説明
code	はい	HTTPレスポンスコード。HTTP Response Status Codeを参照
message	はい	メッセージ

実例

curl -v -X POST --data-binary "@/home/test/0" -H "Authorization:86diNjJlMTI4NDgyZGI1MGJmMWYzZGE2MjllNA==:eyJzY29wZSI6ImltYWdlczpzbGljZS50eHQiLCJkZWFkbGluZSI6IjE0Mzg1ODg0MDYxMDkiLCJvdmVyd3JpdGUiOjAsImZzaXplTGltaXQiOjEwNzM3NDE4MjQsImluc3RhbnQiOjB9" -H "Content-Type:application/octet-stream" -H "Content-Length:2097152" -H "UploadBatch:abcdabcd-abcd-abcd-abcd-abcdabcdabcd" --url "http://uploadDomain/bput/34514eab06922ff67ac7a16cdd28e994/2097152"

---

ファイル作成（Create file）

アップロードしたすべてのデータブロックを指定順序で1つのリソースファイルとして結合します。

リクエスト内容

POST /mkfile/<fileSize>/<UserParam>/<encodUserVars>
    Host: <UploadDomain>
    Authorization:<UploadToken>
    Content-Length:<ctxListSize>
    Content-Type:text/plain;charset=UTF-8
    UploadBatch:<uuid>
    Key:<key>
    MimeType:<mimeType>
    Deadline:<Deadline>
    <ctxList>

ヘッダー説明

パラメータ	必須	説明
Host	はい	Upload Domain Name。コンソールのOverview画面で取得可能。
Authorization	はい	Upload Credential。
Content-Length	はい	全ブロックの<ctx>及び区切り文字の長さ（バイト単位）
Content-Type	はい	固定値 text/plain。
UploadBatch	はい	マルチパートアップロードタスクID（UUID）。
Key	いいえ	Custom File Name。URL-Safe Base64 Encodedが必要。
MimeType	いいえ	カスタムファイルのMIME-Type。
Deadline	いいえ	ファイル保存期間。指定日数を超えたファイルは自動削除されます。単位：日。例：1,2,3… ※0は速やかに削除を意味します。アップロード時に0を設定するのは推奨しません。

パラメータ説明

パラメータ	必須	説明
<fileSize>	はい	リソースファイルのサイズ
<UserParam>	いいえ	カスタム変数。x:で始める必要あり。
<encodedUserVars>	いいえ	カスタム変数値。URL-Safe Base64 Encodedでエンコード必須。

リクエスト内容

リクエストのボディには、各データブロックの最後のアップロード時に得た<ctx>をコンマ区切りで順番に列挙します。最後のアイテムの後にはカンマは不要です。

<lastCtxOfBlock1>,<lastCtxOfBlock2>,<lastCtxOfBlock3>,...,<lastCtxOfBlockN>

レスポンス説明

• 成功時、以下のようなJSONが返却されます。

{
        "hash":"<ContentHash>", 
        "key":"<Key>"
}

フィールド名	必須	説明
code	はい	HTTPリクエストレスポンスコード。HTTP Response Status Codeを参照。
message	はい	メッセージ。

実例

 curl -v -X POST -H 'Authorization:df115a7a498e873b74c2eab217e406a192f0ed14:NzJhMzRhODhhZTA5YjNmNjhkNWJlODY0MDI1NzQ0Nzc1OGExODkwNw==:eyJzY29wZSI6Indoai1zdHlsZS10ZXN0OmZlbnAt5L2g5aW9IUAjJiolZWUubXA0IiwiZGVhZGxpbmUiOiIyNDM4MDc4NjQ3ODMwIiwib3ZlcndyaXRlIjoxLCJmc2l6ZUxpbWl0IjoxMDczNzQxODI0LCJjYWxsYmFja1VybCI6Imh0dHA6Ly9kZW1vLmNvbTo4MS9jYWxsYmFja1VybCIsImNhbGxiYWNrQm9keSI6ImJ1Y2tldD0kKGJ1Y2tldCkma2V5PSQoa2V5KSZmbmFtZT0kKGZuYW1lKSZmc2l6ZT0kKGZzaXplKSZpcD0kKGlwKSZtaW1lVHlwZT0kKG1pbWVUeXBlKSZ1cmw9JCh1cmwpJmNvc3RUaW1lPSQoY29zdFRpbWUpJnVzZXJuYW1lPXdoaiZhZ2U9MTEmcG9zaXRpb249JCh4OnBvc2l0aW9uKSZtZXNzYWdlPSQoeDptZXNzYWdlKSIsImluc3RhbnQiOjB9' -H 'Content-Type:text/plain;charset=UTF-8' -H 'Content-Length:65' -H "UploadBatch:abcdabcd-abcd-abcd-abcd-abcdabcdabcd" --url 'http://uploadDomain/mkfile/6339685/x:position/bG9jYWw=/x:message/dXBsb2Fk' -d "c636ec95ef7a8889dec882ef7eb9306e,d7243df51cb880e11c107088ce942f9c"