JavaScript SDK を使用したファイルのダウンロード - Drive and Photo Service

PDSClient は、単一ファイルをダウンロードするための 2 つのメソッド、downloadFile と createDownloadTask を提供します。このトピックでは、これら 2 つのメソッドを使用してフォトドライブサービス (PDS) からファイルをダウンロードする方法について説明します。

説明

Web クライアントでのファイルのダウンロード:

ブラウザ API の制限により、ブラウザのキャッシュが不足している場合にエラーが報告される場合があり、具体的な原因を特定することは困難です。そのため、Web クライアントでファイルをダウンロードするために downloadFile メソッドまたは createDownloadTask メソッドを使用することはお勧めしません。

Web クライアントでファイルをダウンロードするには、次の方法を使用することをお勧めします。

単一ファイルのダウンロード
listFiles メソッドまたは getFile メソッドを呼び出して、IFileItem オブジェクトの download_url パラメータの値を取得します。ブラウザでダウンロード URL を開いてファイルをダウンロードします。この方法は、ディレクトリ内の複数のファイルまたはファイルではなく、単一ファイルのダウンロードに適しています。
複数のファイルまたはディレクトリ内のファイルのダウンロード
ファイルリストまたはディレクトリ内のすべてのファイルを再帰的にトラバースして、各ファイルの download_url パラメータの値を取得します。フロントエンドでファイルをダウンロードし、ZIP パッケージを生成します。この方法は、複数のファイルまたはディレクトリ内のファイルのダウンロードに適しています。ただし、この方法は大量のメモリを占有するため、大きなファイルまたはディレクトリのダウンロードには適していません。

downloadFile メソッド

便利な方法でファイルをダウンロードします。

await キーワードを使用して、ダウンロードが完了するまで待機できます。
state パラメータの値が stopped、cancelled、または error の場合、PDSError がスローされます。

const cp = await client.downloadFile(pdsFile, downloadTo, options)

例

// from
const pdsFile= {
  drive_id: '1',
  file_id: 'xxxxxxxx',
}

// to (注: ブラウザでファイルをダウンロードする場合、このパラメータを指定する必要はありません。この場合、空の文字列を使用します。)
const downloadTo = '/Users/test/a.txt'

const options = {
  onProgress(state, progress){
    console.log(state, progress)
  }
}

// ファイルをダウンロードします。
await client.downloadFile(pdsFile, downloadTo, options);

console.log('ダウンロードが完了しました。');

リクエストパラメータ

パラメータ	タイプ	必須	説明
pdsFile	Partial<IDownCheckpoint>	はい	ダウンロードするファイル、またはダウンロードチェックポイント情報。
downloadTo	string	はい	ファイルをダウンロードするパス。ブラウザでファイルをダウンロードする場合、このパラメータを指定する必要はありません。この場合、空の文字列を使用します。
options	IDownloadOptions		コールバックメソッドを含むダウンロード設定。

IDownCheckpoint パラメータ

パラメータ	タイプ	必須	説明
path_type	string	はい	ドメインのデータストレージモード。`StandardMode` に設定します。
loc_id	string		ダウンロードするファイルが格納されているドライブまたは共有の ID。`drive_id` パラメータまたは `share_id` パラメータでこのパラメータを置き換えることをお勧めします。
loc_type	string		ダウンロードするファイルの場所タイプ。このパラメータは、`loc_id` パラメータと一緒に使用します。有効な値: `drive` および `share`。
file_key	string		ダウンロードするファイルの一意の識別子。file_key パラメータと file_id パラメータのいずれかを指定する必要があります。
drive_id	string		ドライブ ID。`drive_id` パラメータと `share_id` パラメータのいずれか 1 つのみを指定できます。
share_id	string		共有 ID。`drive_id` パラメータと `share_id` パラメータのいずれか 1 つのみを指定できます。
file_id	string		ダウンロードするファイルの ID。file_key パラメータと file_id パラメータのいずれかを指定する必要があります。
file	IFile	はい	ダウンロードするファイル。
id	string		ダウンロードタスクの ID。
download_id	string		ダウンロード ID。ローカル一時ファイルが作成された場合に生成される ID です。
download_url	string		ダウンロード URL。
content_md5	string		ファイルの MD5 ハッシュ値。
crc64ecma	string		ファイルの CRC-64 値。
content_type	string		ファイルのコンテンツタイプ。
part_info_list	Array<IDownPartInfo>		ダウンロードされたパートのリスト。
state	string		ダウンロードタスクの状態。有効な値: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`。
message	string		エラーメッセージ。
progress	number		ダウンロードタスクの進捗状況。有効な値: 0 から 100。
loaded	number		ダウンロードされたバイト数。単位: `bytes`。
start_time	number		ダウンロードタスクが開始された時刻。単位: `ミリ秒`。
end_time	number		ダウンロードタスクが終了した時刻。単位: `ミリ秒`。
used_avg_speed	number		ファイルがダウンロードされる平均速度。単位: `bytes/s`。
used_time_len	number		ダウンロードタスクに費やされた時間。単位: `ミリ秒`。

次のパラメータのいずれか 1 つのみを指定できます。loc_type と共に loc_id、share_id、および drive_id。
file_key パラメータと file_id パラメータのいずれかを指定する必要があります。

IDownloadOptions (IDownConfig を拡張) パラメータ

パラメータ	タイプ	必須	説明
onReady	(task: UploadTask) => void		タスクの作成後のダウンロードタスクのコールバックメソッド。
onProgress	(state: string, progress:number) => void		タスクの進捗状況をリッスンするために使用されるコールバックメソッド。このメソッドを使用して、ダウンロードの進捗状況と CRC-64 値の計算の進捗状況をリッスンできます。 state の有効な値: running および `checking`。`running` の値は、ダウンロードタスクが進行中であることを指定します。`checking` の値は、CRC-64 値が計算中であることを指定します。 `progress` の有効な値: 0 から 100。
onStateChange	(cp: IDownCheckpoint, state: string, error?: PDSError) => void		タスクの状態変更をリッスンするために使用されるコールバックメソッド。 `state` の有効な値: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`。
onPartComplete	(cp:IDownCheckpoint, part: IPartInfo) => void		パートのダウンロードの完了をリッスンするために使用されるコールバックメソッド。
... その他の IDownConfig パラメータ			その他のパラメータ。

IDownPartInfo パラメータ

パラメータ	タイプ	必須	説明
part_number	number	はい	パートのシーケンス番号。番号は 1 から始まります。
part_size	number	はい	パートのサイズ。

IDownConfig パラメータ

パラメータ	タイプ	必須	説明
verbose	boolean		デバッグログを表示するかどうかを指定します。
checking_crc	boolean		巡回冗長検査 (CRC) 検証を実行するかどうかを指定します。デフォルト値: `true`。
chunk_con_auto	boolean		ダウンロード中の同時実行パートの数を自動的に調整するかどうかを指定します。
init_chunk_con	number		ダウンロードする同時実行パートのカスタム数。このパラメータは、`chunk_con_auto` パラメータを `false` に設定した場合にのみ有効になります。
max_chunk_size	number		パートのサイズ。

レスポンスパラメータ

パラメータ	タイプ	必須	説明
cp	IDownCheckpoint	はい	ダウンロードタスクのチェックポイント情報。この場合、ダウンロードタスクは `success、error、stopped、または cancelled` 状態になっている可能性があります。

createDownloadTask メソッド

ダウンロードタスクを作成します。

const task = client.createDownloadTask(checkpoint, configs)

例

const cp = {
  // to
  file: {
    name: "a.txt",
    path: "/Users/zu/a.txt", // 注: ブラウザでファイルをダウンロードする場合、このパラメータを指定する必要はありません。
    size: 100,
  },

  // from
  path_type: 'StandardMode',
  // loc_type: 'drive',
  // loc_id: '1',        // このパラメータは drive_id パラメータで置き換えることができます。
  // file_key: 'xxxxxxxx'  // このパラメータは file_id パラメータで置き換えることができます。

  drive_id: '1',
  file_id: 'xxxxxxxx'
};

const task = client.createDownloadTask(cp);

リクエストパラメータ

パラメータ	タイプ	必須	説明
checkpoint	IDownCheckpoint	はい	ダウンロードタスクの作成に使用されるパラメータ。
configs	IDownConfig		ダウンロード設定。

レスポンスパラメータ

DownloadTask インスタンスが返されます。

パラメータ	タイプ	必須	説明
task	DownloadTask	はい	ダウンロードタスク。

DownloadTask クラス

ファイルをダウンロードするためのダウンロードタスクを作成します。

サポートされているメソッド

.wait()

このメソッドを呼び出すと、ダウンロードタスクは待機状態になります。state パラメータの値は waiting に変更されます。

.start()

このメソッドを呼び出して、ダウンロードタスクを開始できます。このメソッドを呼び出すと、同時実行パートのダウンロードが開始されます。

task.start();

.stop()

このメソッドを呼び出して、ダウンロードタスクを停止できます。このメソッドを呼び出すと、state パラメータの値は stopped に変更されます。この場合、クライアントインスタンスは次の再開可能なダウンロードのためにチェックポイント情報を格納します。

task.stop();

.cancel()

このメソッドを呼び出して、ダウンロードタスクをキャンセルできます。このメソッドを呼び出すと、state パラメータの値は cancelled に変更されます。

task.cancel()

.getCheckpoint()

このメソッドを呼び出して、ダウンロードタスクのチェックポイント情報を照会できます。このメソッドを呼び出すことに加えて、イベントコールバックを使用してチェックポイント情報を照会することもできます。

var cp = task.getCheckpoint()

.on(eventname, callback)

このメソッドを呼び出して、リスナーを設定できます。

// 例
task.on('progress', (state, progress)=>{
   console.log(state, progress)
})

リクエストパラメータ

パラメータ	タイプ	必須	説明
eventname	string	はい	イベントの名前。有効な値: `progress、statechange、および partialcomplete`。
callback	Function	はい	コールバックメソッド。

サポートされているイベント

次のイベントをリッスンできます。progress、statechange、および partialcomplete。

progress イベントのコールバックメソッド

task.on('progress', (state, progress)=>{
})

リクエストパラメータ

パラメータ

タイプ

必須

説明

state

string

はい

ダウンロードタスクの状態。

state の有効な値: running および checking。running の値は、ダウンロードタスクが進行中であることを指定します。checking の値は、CRC-64 値が計算中であることを指定します。

progress

number

はい

ダウンロードタスクの進捗状況。有効な値: 0 から 100。

statechange イベントのコールバックメソッド

task.on('statechange', (checkpoint, state, error)=>{
})

パラメータ	タイプ	必須	説明
checkpoint	IDownCheckpoint	はい	ダウンロードタスクのチェックポイント情報。
state	string	はい	ダウンロードタスクの状態。有効な値: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`。
error	PDSError		ダウンロードエラー。状態が `error`、`stopped`、または `cancelled` の場合に値が返されることがあります。

partialcomplete イベントのコールバックメソッド

task.on('partialcomplete', (checkpoint, partInfo)=>{
})

パラメータ	タイプ	必須	説明
checkpoint	IDownCheckpoint	はい	ダウンロードタスクのチェックポイント情報。
partInfo	IDownPartInfo	はい	ダウンロードされたパートに関する情報。

状態

次の表に、ダウンロードタスクの考えられる状態を示します。

状態	説明
waiting	ダウンロードタスクは開始待ちです。デフォルトでは、ダウンロードタスクは作成後にこの状態になります。`wait()` メソッドを呼び出して、この状態をトリガーできます。
start	ダウンロードタスクが開始されます。`start()` メソッドを呼び出して、この状態をトリガーできます。
created	ダウンロードタスクが作成されます。この状態は、ローカル一時ファイルが作成された後にトリガーされます。
running	ダウンロードタスクは進行中です。
stopped	ダウンロードタスクは停止されています。
complete	ダウンロードタスクは完了しましたが、ファイルは検証されていません。
checking	ファイルに対して `CRC-64` 検証が実行されています。
success	ダウンロードタスクは成功しました。
error	ダウンロードタスクは失敗しました。この状態は、ダウンロードプロセス中に API 操作の呼び出しに失敗した場合、ネットワーク接続に失敗した場合、またはローカル I/O 操作に失敗した場合にトリガーされます。
cancelled	ダウンロードタスクはキャンセルされました。`.cancel()` メソッドを呼び出して、この状態をトリガーできます。

使用される可能性のあるパラメータ

パラメータ	タイプ	説明
speed	number	ダウンロード速度。単位: `byte/s`。このパラメータは、タスクの状態が実行中の場合にのみ有効です。
progress	number	ダウンロードタスクの進捗状況。有効な値: 0 から 100。
loaded	number	ダウンロードされたパートのサイズ。単位: `bytes`。
file	IFile	ファイルに関する情報。
left_time	number	残りのパートに必要な概算時間。単位: `秒`。
start_time	number	ダウンロードタスクが開始された時刻。単位: `ミリ秒`。
end_time	number	ダウンロードタスクが終了した時刻。単位: `ミリ秒`。
used_avg_speed	number	平均ダウンロード速度。単位: `byte/s`。
used_time_len	number	ダウンロードの期間。単位: `ミリ秒`。