cpコマンドを使用して、Object Storage Service (OSS) からローカルデバイスに画像やビデオなどのリソースをダウンロードできます。 たとえば、複数のオブジェクトをダウンロードしたり、限られたダウンロード速度でオブジェクトをダウンロードしたり、バージョン管理が有効なバケットに特定のバージョンのオブジェクトをダウンロードしたりできます。
使用上の注意
オブジェクトをダウンロードするには、
oss:GetObjectまたはoss:ListObjects権限が必要です。 詳細については、「RAMユーザーへのカスタムポリシーのアタッチ」をご参照ください。このトピックでは、64ビットLinuxシステムに基づくサンプルコマンドラインを提供します。 他のシステムのために、取り替えて下さい./ossutil64対応するバイナリ名を持つコマンドで 詳細は、「ossutilコマンドリファレンス」をご参照ください。
コマンド構文
./ossutil64 cp cloud_url file_url
[-r, --recursive]
[-f --force]
[-u --update]
[--maxdownspeed <value>]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--range <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--snapshot-path <value>]
[--disable-crc64]
[--payer <value>]
[--partition-download <value>]
[-j, --job <value>]
[--parallel <value>]
[--version-id <value>]
[--start-time <value>]
[--end-time <value>]次の表に、コマンド構文のパラメーターとオプションを示します。
パラメータ /オプション | 説明 |
cloud_url | OSSオブジェクトのパス。 パス形式は |
ファイル_url | ローカルファイルのパス。 例: Linuxの場合は |
-r, -- recursive | 再帰を指定します。 このオプションを指定すると、指定された条件を満たすバケット内のすべてのオブジェクトに対して操作が実行されます。 このオプションを指定しない場合、指定されたオブジェクトに対してのみ操作が実行されます。 |
-f -- 力 | 確認を必要とせずに操作を強制します。 |
-u, -- update | ターゲットファイルがローカルデバイスに存在しない場合、またはソースオブジェクトの最終変更時刻がターゲットファイルの最終変更時刻よりも遅い場合にのみ、ossutilがOSSからオブジェクトをダウンロードするように指定します。 |
-- maxdownspeed | 最大ダウンロード速度。 単位: KB/s。 デフォルト値は0で、ダウンロード速度が無制限であることを示します。 |
-- disable-無視-エラー | バッチ操作中にエラーが無視されないように指定します。 |
-- only-current-dir | 現在のディレクトリ内のオブジェクトのみをダウンロードするように指定します。 現在のディレクトリ内のサブディレクトリおよびこれらのサブディレクトリ内のオブジェクトはダウンロードされません。 |
-- bigfile-threshold | 再開可能ダウンロードを使用するためのオブジェクトサイズのしきい値。 オブジェクトのサイズが指定されたオブジェクトサイズのしきい値を超える場合、オブジェクトは再開可能ダウンロードを使用してダウンロードされます。 単位：バイト デフォルトのオブジェクトサイズのしきい値は100 MBです。 有効な値: 0 ~ 9223372036854775807 |
-- 部分サイズ | 部品サイズ。 単位：バイト デフォルトでは、ossutilはオブジェクトサイズに基づいて部品サイズを決定します。 有効な値: 1 ~ 9223372036854775807 |
-- checkpoint-dir | 再開可能ダウンロードタスクのチェックポイント情報を格納するディレクトリを指定します。 タスクが失敗すると、ossutilは自動的にという名前のディレクトリを作成します。 |
-- 範囲 | 特定の範囲のオブジェクトコンテンツをダウンロードし、新しいファイルとして宛先パスに保存することを指定します。 範囲の最小開始値は0で、オブジェクトのコンテンツのバイト0を示します。 このオプションの値は、次のいずれかの形式で指定できます。
|
-- encoding-type | オブジェクトの名前をエンコードするために使用されるメソッド。 このオプションを指定する場合は、値をurlに設定します。 このオプションを指定しない場合、オブジェクトの名前はエンコードされません。 |
-含める | 指定された条件を満たすすべてのオブジェクトを含みます。 詳細については、「オプション -- includeおよび -- exclude」をご参照ください。 |
-除外 | 指定された条件を満たすすべてのオブジェクトを除外します。 詳細については、「オプション -- includeおよび -- exclude 」をご参照ください。 |
-メタ | オブジェクトメタデータ。 オブジェクトメタデータを |
-- acl | オブジェクトのアクセス制御リスト (ACL) 。 有効な値：
|
-- snapshot-path | ダウンロードしたオブジェクトのスナップショットを保存するディレクトリを指定します。 次のダウンロードタスクでは、ossutilはこのディレクトリのスナップショットを読み取り、増分オブジェクトのみをダウンロードします。 |
-- disable-crc64 | 64ビット巡回冗長検査を無効にする (CRC-64) 。 デフォルトでは、ossutilはデータ送信中にCRC-64を有効にします。 |
-- 支払人 | トラフィックとリクエスト料金の支払人。 指定したパスのリソースにアクセスするリクエスタにトラフィックとリクエスト料金を支払う場合は、このオプションをrequesterに設定します。 |
-- partition-download | ダウンロードするパーティション。 このオプションの値は、 |
-j, -- job | 複数のオブジェクトで実行できる同時タスクの数。 有効な値: 1 ~ 10000 デフォルト値: 3。 |
-- 平行 | 1つのオブジェクトに対して実行できる同時タスクの数。 有効な値: 1 ~ 10000 このオプションを設定しない場合、ossutilは操作タイプとオブジェクトサイズに基づいて値を指定します。 |
-- version-id | ダウンロードするオブジェクトのバージョンID。 このオプションは、バージョン管理が有効になっているバケット内のオブジェクトに対してのみ使用できます。 |
-- 開始時間 | オブジェクトをフィルタリングする時間範囲の始まり。 この値は UNIX タイムスタンプです。 最終変更時刻がUNIXタイムスタンプより前のオブジェクトは無視されます。 説明 ossutil V1.7.18以降のみがこのパラメータをサポートしています。 ossutilの更新方法の詳細については、「update」をご参照ください。 |
-終了時間 | オブジェクトをフィルタリングする時間範囲の終わり。 この値は UNIX タイムスタンプです。 最終変更時刻がUNIXタイムスタンプより後のオブジェクトは無視されます。 説明
|
デフォルトの同時実行値がパフォーマンス要件を満たさない場合は、-j、-- jobs、-- parallelオプションを使用してパフォーマンスを調整できます。 デフォルトでは、ossutilはオブジェクトサイズに基づいて -- parallelの値を計算します。 複数のラージオブジェクトをダウンロードする場合、実際の同時タスク数は、-j, -- jobsの値に -- parallelの値を掛けたものになります。
ECSインスタンスまたはサーバーのネットワーク帯域幅、メモリ、CPUなどのリソースが制限されている場合は、同時タスク数を100未満の値に調整することを推奨します。 ネットワーク帯域幅、メモリ、CPUなどのリソースがアイドル状態のままである場合、同時実行タスクの数を増やすことができます。
同時タスクの数が多すぎると、スレッドがリソースを切り替えて競合するため、ossutilのダウンロードパフォーマンスが低下する可能性があります。 さらに、EOF (end-of-file) エラーが発生することがある。 これらの問題を防ぐために、使用可能なリソースに基づいて -j、-- jobs、-- parallelオプションの値を調整できます。 ストレステストを実行するには、最初に2つのオプションに小さな値を指定し、値を徐々に増やして最適な値を見つけることをお勧めします。
サンプル環境
このトピックでは、オブジェクトはOSSからLinuxのローカルディレクトリにダウンロードされます。 実際のビジネスシナリオでサンプルコマンドを使用する場合は、オペレーティングシステムと環境に基づいてオプションとパラメーターの設定を変更します。 サンプル環境:
オペレーティングシステム: Linux
バケツ: examplebucket
バケット内のディレクトリ: destfolder
ローカルファイル: examplefile.txt (ルートディレクトリに格納)
ローカルディレクトリ: localfolder (ルートディレクトリ内)
単一のオブジェクトをダウンロードする
ダウンロードしたオブジェクトの名前を指定しない場合、ダウンロードしたオブジェクトの名前は元のオブジェクトと同じになります。 ダウンロードしたオブジェクトの名前を指定した場合、ダウンロードしたオブジェクトは指定した名前を使用します。
ダウンロードしたオブジェクトを元のオブジェクトの名前で保存する
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/ダウンロードしたオブジェクトをカスタム名で保存する
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt
一度に複数のオブジェクトをダウンロードする
cpコマンドで複数のオブジェクト名を直接指定して、一度に複数のオブジェクトをダウンロードすることはできません。 ただし、cpコマンドを実行して、次の方法を使用して一度に複数のオブジェクトをダウンロードできます。
特定のタイプのオブジェクトをダウンロードする
名前に同じ接頭辞または接尾辞を持つオブジェクトなど、名前が特定のパターンを持つ複数のオブジェクトをダウンロードする場合は、-- includeおよび -- excludeオプションを使用して、指定された条件を満たすオブジェクトをダウンロードできます。
次のコマンドを実行して、JPG形式以外のすべてのオブジェクトをダウンロードします。
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg" -r次のコマンドを実行して、名前にabcを含み、JPG形式またはTXT形式ではないすべてのオブジェクトをダウンロードします。
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
ディレクトリとそのサブディレクトリをダウンロードする
次のコマンドを実行して、ディレクトリ内のサブディレクトリを含むディレクトリ内のすべてのオブジェクトをダウンロードできます。
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/バッチダウンロードタスクが失敗した場合、または増分ダウンロードタスクを実行する場合は、-- updateオプションまたはその短縮形式 -uを使用して、ダウンロードされたオブジェクトをスキップできます。 オブジェクトがローカルファイルと同じ名前でない場合、またはオブジェクトが同じ名前のローカルファイルより後に最後に変更された場合、ossutilはオブジェクトをダウンロードします。 オブジェクトの名前がローカルファイルと同じで、同じ名前のローカルファイルがオブジェクトの最後に変更された場合、ossutilはオブジェクトをスキップします。 サンプルコマンド:
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --updateディレクトリのダウンロード (サブディレクトリを除く)
現在のディレクトリのみをダウンロードし、そのサブディレクトリをダウンロードしない場合は、-- only-current-dirオプションを使用します。 サンプルコマンド:
./ossutil64 cp oss://examplebucket/destfolder/ localfolder/ --only-current-dir -rディレクトリのダウンロード (コマンドで指定されたタイムスタンプ付き)
次のサンプルコマンドは、最終変更時刻が2023年10月31日10:09:18 (UTC + 8) から10月31日12:55:58 (UTC + 8) 2023の範囲内のオブジェクトをディレクトリとそのサブディレクトリからダウンロードします。
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --start-time 1698718158 --end-time 1698728158バケットのルートディレクトリにあるすべてのオブジェクトをダウンロードする
次のサンプルコマンドは、examplebucketという名前のバケットのルートディレクトリにあるすべてのオブジェクトをlocalfolder /という名前のローカルディレクトリにダウンロードします。
./ossutil64 cp -r oss://examplebucket localfolder/
ダウンロード速度の制限
最大ダウンロード速度を制限するには、-- maxdownspeedオプションを指定します。 単位: KB/s。 サンプルコマンド：
指定されたオブジェクトをOSSからダウンロードします。最大ダウンロード速度は1メガバイト/秒に制限されています。
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --maxdownspeed 1024指定されたディレクトリをOSSからダウンロードし、最大ダウンロード速度は1メガバイト/秒に制限されています。
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --maxdownspeed 1024
オブジェクトのコンテンツの範囲をダウンロードする
オブジェクトのコンテンツの範囲をダウンロードするには、-- rangeオプションを指定します。 たとえば、次のコマンドを実行して、examplefile.txtオブジェクトの10〜20文字目をローカルデバイスにファイルとしてダウンロードできます。
./ossutil64 cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --range=10-20
Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).一度に複数のオブジェクトをダウンロードし、スナップショット情報を生成する
一度に複数のオブジェクトをダウンロードするときに -- snapshot-pathオプションを指定した場合、ossutilはオブジェクトのスナップショットを生成し、指定したディレクトリにスナップショット情報を保存します。 このオプションを指定すると、ossutilは指定されたディレクトリからスナップショット情報を読み取り、次にオブジェクトをダウンロードするときに増分オブジェクトのみをダウンロードします。 詳細については、「オブジェクトのアップロード用スナップショットの生成」をご参照ください。
./ossutil64 cp -r oss://examplebucket/destfolder/ localfolder/ --snapshot-path=path バージョン管理が有効なバケットから指定されたバージョンのオブジェクトをダウンロードする
バケットのバージョン管理を有効にすると、バケット内で上書きまたは削除されたオブジェクトは以前のバージョンとして保存されます。 cpコマンドで -- version-idオプションを指定して、指定したバージョンのオブジェクトをダウンロードできます。
./ossutil64 cp oss://my-bucket/test.jpg localfolder/ --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRkオブジェクトのダウンロードに -- version-idオプションを使用するには、ls -- all-versionsコマンドを実行してオブジェクトのバージョンidを取得する必要があります。
-- version-idオプションをコマンドで指定すると、バージョン管理が有効なバケットからのみオブジェクトをダウンロードできます。 バケットのバージョン管理を有効にする方法の詳細については、「バケットバージョン管理」をご参照ください。
一般的なオプション
ossutilを使用して別のリージョンにあるバケットに切り替える場合は、コマンドに -eオプションを追加して、指定したバケットがあるリージョンのエンドポイントを指定します。 ossutilを使用して別のAlibaba Cloudアカウントに属するバケットに切り替える場合、コマンドに -iオプションを追加して、指定されたアカウントのAccessKey IDを指定し、コマンドに -kオプションを追加して、指定されたアカウントのAccessKey secretを指定します。
指定するエンドポイントは、バケットが配置されているリージョンに対応している必要があります。 詳細は、「リージョンとエンドポイント」をご参照ください。
たとえば、次のコマンドを実行して、別のAlibaba Cloudアカウントが所有し、中国 (上海) リージョンにあるexamplebucketバケットのルートディレクトリにあるexampleobject.txtオブジェクトをlocalfolderという名前のローカルディレクトリにダウンロードできます。
./ossutil64 cp oss://examplebucket/exampleobject.txt localfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****共通オプションの詳細については、「共通オプション」をご参照ください。