メインコンテンツへスキップ
大きいファイルをアップロードする際は、そのファイルを小さいパーツに分割し、パーツのアップロードAPIを使用してそれらのパーツをアップロードできます。

アップロードセッションを作成

最初にします。結果のオブジェクトにより、各パーツのサイズとアップロードするパーツの数が定義されます。

ファイルの分割

ファイルをアップロードするパーツに分割します。コマンドラインを使用する場合は、splitコマンドを使用します。
例:
このコマンドにより、ファイルがいくつかのファイルに分割されます。

SHAダイジェストの取得

各パーツを検証するためにSHA-1またはSHA-512ダイジェストを使用できます。SHAダイジェストの値を取得するには、次のいずれかのOpenSSLコマンドを使用して、ファイルのパーツをエンコードします。
例:
これにより、アップロードの検証に使用する、Base64でエンコードされたメッセージが得られます。これをSHA-1の場合はsha=BASE64_ENCODED_DIGEST、SHA-512の場合はsha-512=BASE64_ENCODED_DIGESTの形式でdigestヘッダーに渡します。

Boxに保存されているパーツのスキップ

あるファイルの新バージョンをアップロードする場合には、パーツのアップロードに先立ってアップロードセッションの計画を作成できます。この計画の作成は必須ではありませんが、計画を作成すると、過去のバージョンのファイルからBoxに保存されているパーツを把握できます。 計画リクエストには、各パーツのSHA-512ハッシュが必要です。このハッシュは、小文字かつ128文字の16進数文字列です。ハッシュを取得するには、以下のOpenSSLコマンドを使用します。
例:
各パーツのoffset、size、sha512をに送信します。レスポンスでは、パーツが以下の2つのリストに分割して示されます。
  • hits: Boxにすでに保存されており、アップロードセッションに追加されているパーツ。こちらに記載されているパーツは、アップロードしないでください。
  • misses: Boxに保存されていないパーツ。こちらに記載されているパーツは、次のセクションに従ってアップロードします。
同じペイロードであれば、計画リクエストを何度でも安全に再試行できます。する際は、アップロードしたパーツとhitsの両方を含めてください。

Upload part

アップロードするパーツのデータをアップロードします。その際、パーツのバイト範囲と、コンテンツを適切にアップロードするためのSHAダイジェストを指定します。アップロードセッションの計画を作成した場合には、missesに列挙されているパーツのみをアップロードします。

コンテンツの範囲

各パーツのサイズは、作成したアップロードセッションで指定されているパーツサイズとまったく同じサイズである必要があります。ただし、ファイルの最後のパーツは小さくなる可能性があるため、例外となります。Content-Rangeパラメータの定義は、次のパターンに従います。
Content-Rangeの値を指定する際は、以下の点に注意してください。
  • 各パーツのバイト範囲の下限は、パーツサイズの倍数にする必要があります。
  • 上限は、パーツサイズの倍数から1を引いた値にする必要があります。
たとえば、パーツサイズが8388608の場合、最初の2つのパーツのコンテンツの範囲は次のようになります。

レスポンス

各アップロードの後、結果のレスポンスには、アップロードされたパーツのIDおよびSHAハッシュが含まれます。
レスポンスには常にsha512が小文字の16進数文字列として含まれます。sha1が含まれるのは、SHA-1ダイジェストを使用してパーツをアップロードした場合のみです。
パーツのアップロードから返されたJSONレスポンスと、(セッションの計画を作成した場合には) 計画のレスポンスのhitsはすべて保存しておいてください。いずれも、の際に必要になります。

範囲の重複

パーツアップロードのリクエストがエラーコードrange_overlaps_existing_partで失敗するのは、アプリケーションがファイルの分割に失敗し、すでにコンテンツがアップロードされている範囲にパーツをアップロードしようとしたことが原因です。アプリケーションでは、この最後のパーツがセッションに継続されなかったと想定する必要があります。

並行アップロード

パーツは並行してアップロードできますが、可能な限り順番にアップロードするようにしてください。バイトオフセットが小さいパーツは、バイトオフセットが大きいパーツより先にアップロードする必要があります。 推奨されるのは、バイトオフセット順に並べたパーツのキューから、3~5個のパーツを並行してアップロードする方法です。パーツのアップロードが失敗した場合は、さらにパーツをアップロードする前に、失敗したアップロードを再試行してください。
最終更新日 2026年11月4日