このトピックでは、Drive and Photo Service (PDS) にファイルをアップロードするためのベストプラクティスについて説明します。本トピックを参考にして、PDS にファイルをアップロードできます。
用語
フォルダー:ディレクトリタイプのファイルです。フォルダーには物理データは含まれません。PDS の CreateFile API を呼び出してフォルダーを作成できます。
ファイル:非ディレクトリタイプのファイルです。ファイルには物理データが含まれます。ファイルを作成するには、ローカルファイルを PDS にアップロードする必要があります。このトピックでは、PDS にファイルをアップロードする方法について説明します。
ファイルのアップロード
プロセス
PDS にファイルをアップロードするには、次の 3 つの手順を実行します。
CreateFile API を呼び出してファイルを作成し、ファイルを初期化します。PDS は、ファイルのメタデータと、HTTP 経由でファイルをアップロードするための URL を返します。
前の手順で返された URL を使用してファイルをアップロードします。
CompleteFile API を呼び出して、ファイルアップロードを完了します。

手順
次の例は、ローカルファイルを PDS にアップロードする方法を示しています。
1. ファイルの作成
CreateFile API を呼び出してファイルを作成し、ファイルを初期化します。
主要なパラメーター設定:
drive_id = "testDriveId":ファイルをアップロードする drive の ID。
parent_file_id = "root":アップロード先のディレクトリ。root を指定すると、ファイルがルートディレクトリにアップロードされます。
name = "testName.jpg":アップロードするファイルの名前。
type = "file":アップロードするファイルのタイプ。有効な値: file および folder。
size = 13381200:ローカルファイルの実際のサイズ。単位:バイト。
part_info_list = [{"part_number":1},{"part_number":2},{"part_number":3}]:アップロードするファイルのパート。ファイルサイズと、クライアント側で定義した各パートのサイズに基づいてパート数を指定します。アップロードの成功率を向上させ、アップロードを再開できるようにするために、複数のパートを指定できます。この例では、ファイルサイズは約 13 MB で、クライアント側で定義した各パートのサイズは 5 MB です。そのため、3 つのパートをアップロードします。
リクエストボディの例:
{
"drive_id":"testDriveId",
"name":"testName.jpg",
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"size":13381200,
"type":"file"
}レスポンスボディの例:
{
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1,
"upload_url":"https://xxxx1"
},
{
"part_number":2,
"upload_url":"https://xxxx2"
},
{
"part_number":3,
"upload_url":"https://xxxx3"
}
],
"upload_id":"testUploadId",
"rapid_upload":false,
"type":"file",
"file_id":"testFileId",
"revision_id":"testRevisionId",
"domain_id":"testDomainId",
"drive_id":"testDriveId",
"file_name":"testName.jpg"
}主要なレスポンスパラメーター:
file_id: PDS がファイルに割り当てる一意の ID。ファイルの ID は、ドライブ内で一意です。
upload_id: PDS がファイルアップロード処理に割り当てる ID。このアップロード ID は、後続の手順 (ファイルアップロードの完了など) で使用します。
part_info_list: PDS がパートに割り当てるアップロード URL。URL の数は、アップロードするパートの数と同じです。PDS は各パートにアップロード URL を割り当てます。
2. ファイルのアップロード
手順 1 で返された URL に基づいて、ファイルのパートを走査してアップロードします。この例では、PUT HTTP メソッドを使用します。
Java コードの例:
// アップロードするファイルのすべてのパートを走査します。
for (PartInfo uploadPartInfo : partInfoList) {
// ローカルファイル内のパートのシリアル番号を計算します。
int number = uploadPartInfo.getPartNumber();
long pos = (number - 1) * partSize;
long size = Math.min(length - pos, partSize);
byte[] partContent = new byte[(int) size];
// ローカルファイルからパートのデータをメモリに読み込みます。
RandomAccessFile randomAccessFile = new RandomAccessFile(localFile, "r");
randomAccessFile.seek(pos);
randomAccessFile.readFully(partContent, 0, (int) size);
randomAccessFile.close();
// パートをアップロードします。
RequestBody body = RequestBody.create(null, partContent);
Request request = new Request.Builder()
.url(uploadPartInfo.getUploadUrl())
.header("Content-Length", String.valueOf(size))
.put(body)
.build();
OkHttpClient okHttpClient = new OkHttpClient.Builder().build();
Response response = okHttpClient.newCall(request).execute();
// パートが正常にアップロードされたか判定します。
if (!response.isSuccessful()) {
System.out.println(response.body().string() + "\n");
Assert.fail("upload part failed, partNumber:" + number);
return "";
}
System.out.println("upload part success, partNumber:" + number);
}3. ファイルアップロードの完了
ファイルのすべてのパートがアップロードされた後、CompleteFile API を呼び出してファイルアップロードを完了します。
主要なパラメーター設定:
drive_id = "testDriveId":ファイルのアップロード先となるドライブの ID。
file_id = "testFileId":ファイル ID。このパラメーターには、手順 1 で返された file_id パラメーターの値を設定します。
upload_id = "testUploadId":ファイルのアップロードプロセス ID。このパラメーターには、手順 1 で返された upload_id パラメーターの値を設定します。
リクエストボディの例:
{
"drive_id":"testDriveId",
"file_id":"testFileId",
"upload_id":"testUploadId"
}HTTP ステータスコード 200 が返された場合、ファイルはアップロードされています。
レスポンスボディの例:
{
"domain_id":"testDomainId",
"drive_id":"testDriveId",
"file_id":"testFileId",
"parent_file_id":"root",
"type":"file",
"file_extension":"jpg",
"name":"testName.jpg",
"size":13381200,
"status":"available",
"content_hash":"xxxxx",
"created_at":"2023-01-16T11:55:12.166Z",
"updated_at":"2023-01-16T11:55:13.368Z"
}再開可能なアップロード
シナリオ
ファイルのアップロード中に、アップロードを一時停止できます。たとえば、Wi-Fi のみでファイルをアップロードしたい場合、Wi-Fi が利用できない場合はアップロードを一時停止し、Wi-Fi が利用可能になってからアップロードを再開できます。
実装
ファイルをアップロードする際に、ファイルを複数のパートに分割できます。
たとえば、50 MB のファイルをアップロードし、クライアントで定義した各パートのサイズが 5 MB の場合、クライアントはファイルを 10 個のパートに分割します。
![]()
クライアントは最初の 6 つのパートを PDS にアップロード済みで、7 つ目のパートのアップロード中にファイルのアップロードを停止したとします。この場合、クライアントはファイルの情報やアップロードの進捗など、ファイルアップロード処理に関する中間情報を保存する必要があります。クライアントは中間情報をデータベースに保存できます。
![]()
ファイルのアップロードを再開すると、PDS にアップロードされていた 7 番目のパートの部分的なデータは破棄されます。クライアントは、完全にアップロードされていない 7 つ目のパートからファイルのアップロードを再開します。クライアントがファイルのアップロードを再開する際、残りのパートのアップロード URL が無効になり、エラーコード 403 が返される場合があります。この場合、ListUploadedParts API を呼び出して、残りのパートのアップロード URL を取得できます。
ファイルアップロード処理が 10 日を超えて中断された場合、アップロードを再開することはできません。この場合、CreateFile API を呼び出して別のファイルを作成し、ローカルファイルを再度アップロードする必要があります。
高速ファイル転送
概要
PDS は、ドメインレベルでファイルの重複排除機能を提供します。PDS ドメイン内に既に存在するファイルをアップロードする場合、完全なファイルアップロード処理を実行する必要はありません。この場合、ファイルのセキュアハッシュアルゴリズム 1 (SHA-1) ハッシュ値を計算するだけでよく、ファイルを数秒で PDS にアップロードできます。
シナリオ
ユーザー A が PDS のドライブにムービーをアップロード済みの場合、ユーザー B は、高速ファイル転送機能を使用して、同じドメイン内の別の PDS ドライブにそのムービーをアップロードできます。ユーザー B は、ムービーをアップロードするために完全なアップロード処理を実行する必要はありません。これにより、アップロード効率が向上し、アップロードトラフィックを節約できます。
ユーザー B が高速ファイル転送機能を使用して PDS にアップロードしたファイルは、ユーザー A のドライブ内のファイルとは独立しています。これにより、データセキュリティが確保されます。
高速ファイル転送機能の使用
高速ファイル転送機能を使用してファイルをアップロードする前に、ファイルの SHA-1 ハッシュ値を計算する必要があります。CreateFile API を呼び出す際に、content_hash パラメーターに計算したファイルの SHA-1 ハッシュ値を設定する必要があります。
主要なパラメーター設定:
content_hash_name = "sha1":高速ファイル転送の計算アルゴリズム。SHA-1 のみがサポートされています。
content_hash = "xxxx": ファイルから計算された SHA-1 ハッシュ値です。size = 13381200: ファイルのサイズ。
その他のパラメーター設定は、このトピックの「ファイルのアップロード」セクションで説明した内容と同じです。
リクエストボディの例:
{
"drive_id":"testDriveId",
"name":"testName.jpg",
"parent_file_id":"root",
"content_hash":"xxxxx",
"content_hash_name":"sha1",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"size":13381200,
"type":"file"
}ファイルの SHA-1 ハッシュ値を計算する Java コード例:
public static String getFileHash(File file) throws IOException {
return Hex.encodeHexString((getFileHashBytes(file)));
}
public static byte[] getFileHashBytes(File file) throws IOException {
byte[] sha1;
try {
MessageDigest digest = MessageDigest.getInstance("SHA1");
byte[] buffer = new byte[10 * 1024];
FileInputStream is = new FileInputStream(file);
int len;
while ((len = is.read(buffer)) != -1) {
digest.update(buffer, 0, len);
}
is.close();
sha1 = digest.digest();
} catch (NoSuchAlgorithmException e) {
throw new RuntimeException("SHA1 algorithm not found.");
}
return sha1;
}レスポンスボディの例:
{
"domain_id":"testDomainId",
"drive_id":"testDriveId",
"parent_file_id":"root",
"upload_id":"testUploadId",
"rapid_upload":true,
"type":"file",
"file_id":"testFileId",
"revision_id":"testRevisionId",
"file_name":"testName.jpg"
}主要なレスポンスパラメーター:
rapid_upload:高速ファイル転送機能を使用してファイルがアップロードされたかどうかを示します。
true の場合、ファイルは高速ファイル転送機能を使用してアップロードされています。指定された SHA-1 ハッシュ値に基づき、PDS は同一ドメイン内で、アップロード対象ファイルと同じデータを含む既存ファイルを検出します。この場合、レスポンスボディにはファイルのパートのアップロード URL が返されず、クライアントは、ファイルのアップロードとアップロード完了処理を含む後続の手順を実行する必要はありません。
false の場合、ファイルは高速ファイル転送機能を使用してアップロードされていません。この場合、レスポンスボディにはファイルのパートのアップロード URL が含まれます。クライアントは、ファイルのアップロードとアップロード完了処理を含む後続の手順を実行する必要があります。
事前ハッシュ機能を使用した精度の向上
高速ファイル転送機能を使用してファイルをアップロードする前に、ファイルの SHA-1 ハッシュ値を計算する必要があります。多くの場合、クライアントのコンピューティング能力には制限があります。大容量ファイルの完全な SHA-1 ハッシュ値の計算には時間がかかります。さらに、PDS ドメイン内にファイルの SHA-1 ハッシュ値と一致するデータがない場合、高速ファイル転送機能を使用してファイルをアップロードできません。この場合、クライアントの計算リソースが無駄になり、ファイルのアップロードに要する時間が増加します。
この問題を解決し、高速ファイル転送の精度を向上させるために、PDS は事前ハッシュ機能を提供します。ファイルの先頭 1 KB のデータの SHA-1 ハッシュ値のみを計算するだけで十分です。CreateFile API を呼び出す際に、pre_hash パラメーターに、ファイルの先頭 1 KB のデータの計算済み SHA-1 ハッシュ値を設定します。サーバーは、PDS ドメイン内にそのデータが既に存在するかどうかを確認します。
主要なパラメーター設定:
pre_hash = "xxxxx":ファイルの先頭 1 KB のデータの SHA-1 ハッシュ値。
その他のパラメーター設定は、このトピックの「ファイルのアップロード」セクションで説明した内容と同じです。
リクエストボディの例:
{
"drive_id":"10530",
"name":"testName.jpg",
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"pre_hash":"xxxx",
"size":13381200,
"type":"file"
}レスポンスの分析:
HTTP ステータスコード 409 が返された場合、同一ドメイン内のデータがファイルの先頭 1 KB データの SHA-1 ハッシュ値と一致しています。これは、ドメイン内の既存ファイルがアップロード対象ファイルと同じデータを含む可能性があることを示します。この場合、クライアントはファイルの完全な SHA-1 ハッシュ値の計算を続行し、CreateFile API を再度呼び出してから、高速ファイル転送によるアップロードを試行できます。なお、ファイルの先頭 1 KB のデータは高い確率で PDS 内のデータと一致する可能性があるため、事前ハッシュ機能は完全な一致精度を保証するものではありません。
HTTP ステータスコード 201 が返された場合、同一ドメイン内のデータはファイルの先頭 1 KB データの SHA-1 ハッシュ値と一致していません。これは、ドメイン内にアップロード対象ファイルと同じデータを含むファイルが存在しないことを示します。この場合、ファイルのパートのアップロード URL が同期的に返され、クライアントはファイルアップロード処理の後続手順を続行できます。
事前ハッシュ値はバックグラウンドで非同期に計算されるため、結果が返されるまでに数分のレイテンシーが生じる場合があります。ファイルを PDS にアップロードした直後に重複ファイルをアップロードすると、その重複ファイルは高速ファイル転送機能を使用してアップロードされない可能性があります。
フローチャート

上書きモードでのファイルのアップロード
PDS では、既存ファイルを上書きしてファイルをアップロードできます。これを行うには、CreateFile API を呼び出す際に file_id パラメーターに既存ファイルの ID を設定します。その後、通常のファイルアップロード手順に従ってファイルをアップロードします。
リクエストボディの例:
{
"drive_id":"testDriveId",
"file_id":"testFileId",
"name":"testName.jpg",
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"size":13373603,
"type":"file"
}重要なポイント:
ファイルを上書きした後も、ファイルの ID は変更されません。同じファイル ID を使用して、ファイルに対する操作を実行できます。
複数のクライアントが同時に同じファイルを上書きする場合、最後に CompleteFile API を呼び出したクライアントがアップロードしたバージョンが、ファイルの最新バージョンになります。
ファイルを上書きする前のバージョンを保持する場合は、履歴バージョン機能を有効にする必要があります。詳細については、「ListRevision」をご参照ください。
よくある質問
ファイルのパートのアップロード URL の有効期限が切れた場合はどうすればよいですか?
ファイルパートのアップロード用 URL の有効期間は 1 時間です。1 時間経過後にこの URL を使用してファイルのパートをアップロードしようとすると、エラーコード 403 が返されます。たとえば、ファイルのアップロードを停止し、1 時間経過後にアップロードを再開すると、エラーコード 403 が返されます。この場合、アップロードを再開する前に、ListUploadedParts API を呼び出して残りのパートのアップロード URL を取得できます。
ファイルをアップロードする際に注意すべき制限事項は何ですか?
ファイルの各パートのサイズは最大 5 GB です。
サーバーはストリーミングモードでファイルの SHA-1 ハッシュ値を計算します。そのため、単一ファイルの各パートは順番にアップロードする必要があり、同時にアップロードすることはできません。
ファイルのパートは上書きできません。
ファイルアップロード処理の有効期間はどのくらいですか?
10 日以内にファイルアップロード処理を完了する必要があります。完了しない場合、ファイルアップロード処理は破棄されます。この場合、CreateFile API を呼び出して PDS に別のファイルを作成し、ローカルファイルを再度アップロードする必要があります。