このトピックでは、Drive および Photo Service (PDS) にファイルをアップロードするためのベストプラクティスについて説明します。 このトピックを参照して、PDS にファイルをアップロードできます。
用語
フォルダ: ディレクトリタイプのファイル。 フォルダには物理データは含まれていません。 PDS の CreateFile 操作を呼び出して、フォルダを作成できます。
ファイル: ディレクトリ以外のタイプのファイル。 ファイルには物理データが含まれています。 ファイルを作成するには、ローカルファイルを PDS にアップロードする必要があります。 このトピックでは、PDS にファイルをアップロードする方法について説明します。
ファイルのアップロード
プロセス
PDS にファイルをアップロードするには、次の 3 つのステップを実行します。
CreateFile 操作を呼び出して、ファイルを作成し、ファイルを初期化します。 PDS は、ファイルのメタデータと、HTTP 経由でファイルをアップロードするために使用される URL を返します。
前のステップで返された URL を使用して、ファイルをアップロードします。
CompleteFile 操作を呼び出して、ファイルのアップロードプロセスを完了します。
手順
次の例は、ローカルファイルを PDS にアップロードする方法を示しています。
1. ファイルを作成する
CreateFile 操作を呼び出して、ファイルを作成し、ファイルを初期化します。
主要なパラメータ設定:
drive_id = "testDriveId": ファイルのアップロード先のドライブの 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" // 各パートのアップロード URL
},
{
"part_number":2,
"upload_url":"https://xxxx2" // 各パートのアップロード URL
},
{
"part_number":3,
"upload_url":"https://xxxx3" // 各パートのアップロード URL
}
],
"upload_id":"testUploadId", // アップロード ID
"rapid_upload":false, // インスタントファイル転送が使用されたかどうか
"type":"file",
"file_id":"testFileId", // ファイル ID
"revision_id":"testRevisionId", // リビジョン ID
"domain_id":"testDomainId", // ドメイン ID
"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 操作を呼び出して、ファイルのアップロードプロセスを完了します。
主要なパラメータ設定:
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 操作を呼び出して、残りのパーツのアップロード URL を取得できます。
ファイルのアップロードプロセスが 10 日以上中断された場合、再開可能なアップロードを実行できません。 この場合、CreateFile 操作を呼び出して別のファイルを作成し、ローカルファイルを再度アップロードする必要があります。
インスタントファイル転送
概要
PDS は、ドメインレベルでファイルの重複排除機能を提供します。 PDS ドメインに既に存在するファイルをアップロードする場合、完全なファイルアップロードプロセスを実行する必要はありません。 この場合、ファイルのセキュアハッシュアルゴリズム 1 (SHA-1) ハッシュ値を計算するだけで、ファイルを数秒で PDS にアップロードできます。
シナリオ
ユーザー A が PDS のドライブに動画をアップロードした場合、ユーザー B はインスタントファイル転送機能を使用して、同じドメイン内の別の PDS ドライブに動画をアップロードできます。 ユーザー B は、動画をアップロードするために完全なプロセスを実行する必要はありません。 これにより、アップロード効率が向上し、アップロードトラフィックが節約されます。
ユーザー B がインスタントファイル転送機能を使用して PDS にアップロードしたファイルは、ユーザー A のドライブにあるファイルとは独立しています。 これにより、データセキュリティが確保されます。
インスタントファイル転送機能を使用する
インスタントファイル転送機能を使用してファイルをアップロードする前に、ファイルの SHA-1 ハッシュ値を計算する必要があります。 CreateFile 操作を呼び出すときは、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))); // ファイルのハッシュ値を16進数文字列として返す
}
public static byte[] getFileHashBytes(File file) throws IOException {
byte[] sha1;
try {
MessageDigest digest = MessageDigest.getInstance("SHA1"); // SHA-1 アルゴリズムのインスタンスを取得
byte[] buffer = new byte[10 * 1024]; // 10KB のバッファ
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."); // SHA-1 アルゴリズムが見つからない場合の例外
}
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 操作を呼び出すときは、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", // ファイルの最初の 1KB のデータのハッシュ値
"size":13381200,
"type":"file"
}レスポンスの分析:
HTTP ステータスコード 409 が返された場合、同じドメイン内のデータがファイルの最初の 1 KB データの SHA-1 ハッシュ値と一致します。これは、ドメイン内の既存のファイルに、アップロードされるファイルと同じデータが含まれている可能性があることを示します。 この場合、クライアントはファイルの完全な SHA-1 ハッシュ値の計算を続行し、CreateFile 操作を再度呼び出して、インスタントファイル転送機能を使用してファイルをアップロードしようとすることができます。 ファイルの最初の 1 KB のデータは、PDS 内のデータと高い確率で一致する可能性があるため、事前ハッシュ機能では一致の精度が保証されないことに注意してください。
HTTP ステータスコード 201 が返された場合、同じドメイン内のデータがファイルの最初の 1 KB データの SHA-1 ハッシュ値と一致しません。これは、ドメイン内のファイルに、アップロードされるファイルと同じデータが含まれていないことを示します。 この場合、ファイルのパーツのアップロード URL が同期的に返され、クライアントはファイルアップロードプロセスの後続のステップを続行できます。
事前ハッシュ値はバックグラウンドで非同期的に計算され、数分の遅延で返される場合があります。 ファイルが PDS にアップロードされた直後に重複ファイルをアップロードすると、重複ファイルはインスタントファイル転送機能を使用してアップロードされない場合があります。
フローチャート
上書きモードでのファイルのアップロード
PDS では、既存のファイルを上書きしてファイルをアップロードできます。 これを行うには、CreateFile 操作を呼び出すときに、file_id パラメータを既存のファイルの ID に設定します。 次に、通常のファイルアップロードプロセスに従ってファイルをアップロードします。
リクエストボディの例:
{
"drive_id":"testDriveId",
"file_id":"testFileId", // 上書きするファイルの ID
"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 操作を呼び出したクライアントによってアップロードされたファイルのバージョンが、ファイルの最新バージョンとして使用されます。
ファイルが上書きされる前のファイルのバージョンを保持する場合は、履歴バージョン機能を有効にする必要があります。 詳細については、「ListRevision」をご参照ください。
FAQ
ファイルのパーツのアップロード URL の有効期限が切れた場合はどうすればよいですか?
ファイルのパーツのアップロードに使用される URL は、1 時間有効です。 1 時間後に CreateFile 操作を呼び出してファイルのパーツをアップロードすると、エラーコード 403 が返されます。 たとえば、ファイルのアップロードを停止し、1 時間後に再開可能なアップロードを実行すると、エラーコード 403 が返されます。 この場合、再開可能なアップロードを実行する前に、ListUploadedParts 操作を呼び出して、残りのパーツのアップロード URL を取得できます。
ファイルをアップロードする際に注意すべき制限事項は何ですか?
ファイルの各パーツのサイズは最大 5 GB です。
サーバーは、ストリーミングモードでファイルの SHA-1 ハッシュ値を計算します。 したがって、単一ファイルのパーツは順番にアップロードする必要があり、同時にアップロードすることはできません。
ファイルのパーツを上書きすることはできません。
ファイルアップロードプロセスの有効期間はどのくらいですか?
10 日以内にファイルアップロードプロセスを完了する必要があります。 そうしないと、ファイルアップロードプロセスは破棄されます。 この場合、CreateFile 操作を呼び出して PDS に別のファイルを作成し、ローカルファイルを再度アップロードする必要があります。