ファイルをアップロードする - Drive and Photo Service - Alibaba Cloud ドキュメントセンター

PDSClient は、ファイルをアップロードするための 2 つのメソッド uploadFile と createUploadTask を提供します。このトピックでは、これら 2 つのメソッドについて説明します。

uploadFile メソッド

便利な方法でファイルをアップロードします。

await キーワードを使用して、ファイルがアップロードされるまで待機できます。
state の値が stopped、cancelled、または error の場合、PDSError がスローされます。

// client は PDSClient インスタンスを示します。
const cp = await client.uploadFile(from, uploadTo, options)

例

<input type="file" id="f1"/>

<script> 
  document.getElementById('f1').onchange = async function(e){
    let file = e.target.files[0];
    let uploadTo = {drive_id: '1', parent_file_id: 'root'};
    await client.uploadFile(file, uploadTo);
    console.log("Uploaded");
  }
</script>

リクエストパラメーター

パラメーター	タイプ	必須	説明
file	IFile \| string	はい	アップロードするファイル。 Web ブラウザーでファイルをアップロードする場合は、アップロードする HTML ファイルを指定します。 Node.js 環境でファイルをアップロードする場合は、ローカルファイルパスまたはローカルパス情報を設定します。
uploadTo	IUpCheckpoint	はい	ファイルをアップロードする Drive および Photo Service (PDS) ディレクトリに関する情報。最後のチェックポイント情報を設定することもできます。
options	IUploadOptions		コールバックメソッドを含むアップロード構成。

IFile のフィールド

フィールド	タイプ	必須	説明
path	string	はい	パス。
name	string	はい	ファイルの名前。
size	number	はい	ファイルのサイズ。
type	string		ファイルの `content type`。

IUpCheckpoint のフィールド

フィールド	タイプ	必須	説明
file	IFile	はい	アップロードするファイル。 Web ブラウザーでファイルをアップロードする場合は、アップロードする HTML ファイルを指定します。 Node.js 環境でファイルをアップロードする場合は、ローカルパス情報を設定します。
path_type	string	はい	ドメインの `path type`。`StandardMode` に設定します。
loc_id	string		ファイルをアップロードする場所の ID。`drive_id` または `share_id` を指定できます。
loc_type	string		ファイルをアップロードする場所のタイプ。有効な値：`drive` および `share`。
parent_file_key	string		ファイルをアップロードするディレクトリの ID。このパラメーターを `parent_file_id` パラメーターに置き換えることをお勧めします。
drive_id	string		ファイルをアップロードするディレクトリのドライブ ID。`drive_id` パラメーターと `share_id` パラメーターのいずれかを指定する必要があります。
share_id	string		ファイルをアップロードするディレクトリの共有 ID。`drive_id` パラメーターと `share_id` パラメーターのいずれかを指定する必要があります。
parent_file_id	string		ファイルをアップロードするディレクトリの親ディレクトリ ID。
new_name	string		アップロードされたファイルに使用する新しい名前。このパラメーターは、`check_name_mode` パラメーターの影響を受ける可能性があります。
id	string		アップロードタスクの ID。
file_key	string		アップロードするファイルの ID。このパラメーターを file_id パラメーターに置き換えることをお勧めします。
update_id	string		アップロード ID。この ID は、PDS が一時ファイルを作成した後に生成されます。
part_info_list	Array<IUpPartInfo>		アップロードされるパーツのリスト。
state	string		アップロードタスクの状態。有効な値：`waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, and cancelled`。
message	string		エラーメッセージ。
progress	number		アップロードの進捗状況。有効な値： 0 ～ 100 。
loaded	number		アップロードされたバイト数。単位：`bytes`。
chunk_size	number		パーツのサイズ。単位：`bytes`。
start_time	number		アップロードタスクの開始時刻。単位：`millisecond`。
end_time	number		アップロードタスクの終了時刻。単位：`millisecond`。
used_avg_speed	number		ファイルがアップロードされる平均速度。単位：`bytes/s`。
used_time_len	number		アップロードタスクの開始からの経過時間。単位：`millisecond`。

loc_id + loc_type または share_id || drive_id を指定する必要があります。
parent_file_key または parent_file_id を指定する必要があります。

IUploadOptions のフィールド (IUpConfig を拡張)

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

IUpPartInfo のフィールド

フィールド	タイプ	必須	説明
part_number	number	はい	パーツのシーケンス番号。番号は 1 から始まります。
part_size	number	はい	パーツのサイズ。
etag	string		パーツがアップロードされた後に生成される `ETag`。

IUpConfig のフィールド

フィールド	タイプ	必須	説明
parallel_upload	boolean		パーツを同時にアップロードするかどうかを指定します。デフォルト値：`false`。
check_name_mode	string		新しいファイルの名前が既存のファイルと同じ名前の場合に使用されるポリシー。有効な値： `overwrite`：既存のファイルを、既存のファイルと同じ名前のファイルで上書きします。 `auto_rename`：ファイル名の末尾に乱数を追加します。 `refuse`：既存のファイルと同じ名前のファイルは作成しません。 `ignore`：既存のファイルと同じ名前のファイルを作成します。
checking_crc	boolean		CRC 検証を実行するかどうかを指定します。デフォルト値：`true`。
chunk_con_auto	boolean		アップロードされている同時実行パーツの数を自動的に調整するかどうかを指定します。
init_chunk_con	number		アップロードする同時実行パーツのカスタム数。このフィールドは、`chunk_con_auto` が `false` に設定されている場合にのみ有効になります。
max_chunk_size	number		パーツのサイズ。
ignore_rapid	boolean		インスタントファイル転送を強制的に無効にするかどうかを指定します。デフォルト値：`false`。このフィールドはテストに使用できます。

レスポンスパラメーター

パラメーター	タイプ	必須	説明
cp	IUpCheckpoint	はい	アップロードタスクのチェックポイント情報。有効な状態には、`success`、`rapid_success`、`error`、`stopped`、および `cancelled` が含まれます。

createUploadTask メソッド

アップロードタスクを作成します。

const task = client.createUploadTask(checkpoint, configs)

例

<input type="file" id="f1"/>

<script> 
  document.getElementById('f1').onchange = async function(e){
    let file = e.target.files[0];
    let cp = {
      
      // from
      file,
      
      // to
      path_type: "StandardMode",
      // loc_id: "1", // drive_id パラメーターで置き換えることができます。
      // loc_type: "drive",
      // parent_file_key: "root", // parent_file_id パラメーターで置き換えることができます。
      
      drive_id: "1", 
      parent_file_id: "root"
    };
  
    // アップロードタスクを作成します。
    const task = client.createUploadTask(cp);
    
    // アップロードの進捗状況をリッスンします。
    task.on('progress', (state, progress)=>{
       console.log(state, progress);
    });
  
    // アップロードタスクを開始します。
    task.start();
   
    // ...
  }
</script>

リクエストパラメーター

パラメーター	タイプ	必須	説明
checkpoint	IUpCheckpoint	はい	アップロード属性。
configs	IUpConfig		アップロード構成。

レスポンスパラメーター

パラメーター	タイプ	必須	説明
task	UploadTask	はい	UploadTask インスタンス。

UploadTask クラス

ファイルをアップロードするタスクを作成します。

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

.wait()

このメソッドを呼び出すと、タスクの状態が waiting に変わります。

.start()

このメソッドを呼び出して、アップロードタスクを開始できます。アップロードタスクを開始すると、システムは SHA-1 ハッシュ値の計算を開始します。ファイルが即座にアップロードされた場合は、インスタントファイル転送の成功を示すメッセージが返されます。ファイルが即座にアップロードできない場合は、システムはファイルのパーツをアップロードすることによってファイルのアップロードを開始します。config.parallel_upload パラメーターは、パーツを同時にアップロードするかどうかを指定します。

task.start();

.stop()

このメソッドを呼び出して、アップロードタスクを一時停止できます。タスクの state は stopped に変わります。この場合、クライアントインスタンスは、次の再開可能なアップロードのために checkpoint 情報を保存します。

task.stop();

.cancel()

このメソッドを呼び出して、アップロードタスクをキャンセルできます。タスクの状態は cancelled に変わります。

task.cancel()

.getCheckpoint()

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

IUpCheckpoint cp = task.getCheckpoint()

.on(eventname, callback)

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

// 例： progress イベント
task.on('progress', (state, progress)=>{
   console.log(state, progress)
})

パラメーター

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

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

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

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

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

パラメーター

パラメーター

タイプ

必須

説明

state

string

はい

タスクの状態。

有効な値：computing_hash、running、および checking。computing_hash の値は、SHA-1 ハッシュ値が計算中であることを示します。running の値は、アップロードタスクが進行中であることを示します。checking の値は、CRC-64 値が計算中であることを示します。

progress

number

はい

アップロードの進捗状況。有効な値： 0 ～ 100 。

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

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

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

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

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

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

状態

アップロードタスクは、次のいずれかの状態になります。

状態	説明
waiting	アップロードタスクは開始待ちです。デフォルトでは、アップロードタスクは作成後にこの状態になります。`wait()` メソッドを呼び出して、この状態をトリガーできます。
start	アップロードタスクが開始されます。`start()` メソッドを呼び出して、この状態をトリガーできます。
created	アップロードタスクが作成されます。この状態は、PDS が一時ファイルを作成した後にトリガーされます。この場合、`upload ID` が生成されます。
computing_hash	`SHA-1` ハッシュ値が計算されています。これは、インスタントファイル転送に使用されます。ファイルが即座にアップロードされると、タスクの状態は次のようになります。 `rapid_success`。
running	アップロードタスクが実行中です。
stopped	アップロードタスクが一時停止されています。
complete	アップロードタスクは完了しましたが、ファイルは検証されていません。
checking	ファイルに対して `CRC-64` 検証が実行されています。
success	アップロードタスクは成功しました。
rapid_success	ファイルが即座にアップロードされました。
error	アップロードタスクが失敗しました。この状態は、API 操作の呼び出しに失敗した場合、ネットワーク接続に失敗した場合、またはアップロードプロセス中にローカル I/O 操作に失敗した場合にトリガーされます。
cancelled	アップロードタスクがキャンセルされました。`.cancel()` メソッドを呼び出して、この状態をトリガーできます。

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

// 例：
console.log(task.speed)

パラメーター	タイプ	説明
speed	number	アップロード速度。単位：`byte/s`。このパラメーターは、タスクの状態が running の場合にのみ有効です。
progress	number	アップロードの進捗状況。有効な値： 0 ～ 100 。
loaded	number	アップロードされたパーツのサイズ。単位：`bytes`。
file	IFile	ファイルに関する情報。
left_time	number	残りのパーツのアップロードに必要な概算時間。単位：`seconds`。
start_time	number	アップロードタスクの開始時刻。単位：`millisecond`。
end_time	number	アップロードタスクの終了時刻。単位：`millisecond`。
used_avg_speed	number	平均アップロード速度。単位：`byte/s`。
used_time_len	number	アップロードの期間。単位：`millisecond`。