cp コマンドを使用してローカルファイルを OSS にアップロードする方法 - Object Storage Service

cp コマンドを使用して、ローカルファイルまたはディレクトリを指定のバケットにアップロードします。このコマンドは、シンプルアップロード、再開可能なアップロード、バッチアップロード、増分アップロードをサポートしています。また、アップロード中にオブジェクトのメタデータ、ストレージクラス、アクセス制御リスト (ACL) などの詳細を指定することもできます。

仕組み

cp コマンドを使用してファイルをアップロードすると、ossutil はファイルサイズに基づいてアップロード方法を自動的に選択します。

シンプルアップロード：再開可能なアップロードのしきい値より小さいファイルに使用されます。デフォルトのしきい値は 100 MB で、--bigfile-threshold オプションで変更できます。
再開可能なアップロード：しきい値以上のファイルに使用されます。アップロードが中断された場合、アップロードされたパートはバケットに一時的に保存されます。ストレージコストを避けるために、これらのパートを定期的にクリーンアップする必要があります。手動でパートを削除するか、自動削除のためのライフサイクルルールを設定できます。

注意事項

ossutil 1.6.16 以降、サポートされているすべてのオペレーティングシステムで ossutil をバイナリ名として使用できます。以前のバージョンでは、お使いのシステムに固有の OS バイナリ名を使用する必要があります。詳細については、「ossutil コマンドリファレンス」をご参照ください。

権限

デフォルトでは、Alibaba Cloud アカウントはすべての操作に対する完全な権限を持っています。ただし、Resource Access Management (RAM) ユーザーまたは RAM ロールにはデフォルトで権限がありません。Alibaba Cloud アカウントのオーナーまたは管理者は、RAM ポリシーまたはバケットポリシーを使用して権限を付与する必要があります。

API アクション	説明
`oss:PutObject`	オブジェクトをアップロードします。
`oss:PutObjectTagging`	任意。オブジェクトをアップロードしてそのタグを設定する場合に必要です。
`kms:GenerateDataKey`	任意。オブジェクトをアップロードし、KMS によるサーバーサイド暗号化を有効にする場合に必要です。
`kms:Decrypt`	任意。オブジェクトをアップロードし、KMS によるサーバーサイド暗号化を有効にする場合に必要です。

コマンド構文

ossutil cp file_url cloud_url [options]

次の表に、パラメーターとオプションを説明します。

パラメーター	説明
file_url	ローカルファイルのパス。ソースがディレクトリの場合、パスはパス区切り文字 (/ または \) で終わる必要があります。たとえば、Linux システムでは `/localfolder/examplefile.txt`、Windows システムでは `D:\localfolder\examplefile.txt` です。
cloud_url	オブジェクトのパス。フォーマットは `oss://bucket[/prefix]` です。例：`oss://examplebucket/examplefile.txt`。
-r, --recursive	操作を再帰的に実行します。このオプションを指定すると、ossutil はバケット内の一致するすべてのオブジェクトに対して操作を実行します。それ以外の場合、ossutil は指定された単一のオブジェクトに対してのみ操作を実行します。
-f --force	確認プロンプトを表示せずに、操作を強制実行します。
-u，--update	宛先オブジェクトが存在しない場合、またはソースファイルが宛先オブジェクトよりも最近変更された場合にのみファイルをアップロードします。
--maxupspeed	最大アップロード速度。単位：KB/s。デフォルト値は 0 で、アップロード速度が無制限であることを示します。
--enable-symlink-dir	リンクされたサブディレクトリをアップロードします。このオプションはデフォルトで無効になっています。
--disable-all-symlink	アップロード中にすべてのリンクされたサブファイルとリンクされたサブディレクトリを無視します。
--disable-ignore-error	バッチ操作中にエラーを無視しません。
--only-current-dir	指定されたソースディレクトリ内のファイルのみをアップロードし、そのサブディレクトリは無視します。
--bigfile-threshold	再開可能なアップロードのサイズしきい値。単位：バイト。デフォルト値：100 MB 有効値：0～9223372036854775807
--part-size	各パートのサイズ。単位：バイト。デフォルトでは、ossutil はファイルサイズに基づいて適切なパートサイズを計算します。有効値：1～9223372036854775807
--checkpoint-dir	再開可能なアップロードのレコードを保存するディレクトリ。再開可能なアップロードが失敗した場合、ossutil は自動的に `.ossutil_checkpoint` という名前のディレクトリを作成し、そこにチェックポイント情報を記録します。再開可能なアップロードが成功すると、ディレクトリは削除されます。このオプションを指定する場合は、指定したディレクトリが削除可能であることを確認してください。
--encoding-type	ファイル名のエンコード形式。値を url に設定します。このオプションを指定しない場合、ファイル名はエンコードされません。
--include	指定された条件を満たすすべてのファイルを含めます。構文と例の詳細については、「指定された条件を満たすファイルのバッチアップロード」をご参照ください。
--exclude	指定された条件を満たすすべてのファイルを除外します。構文と例の詳細については、「指定された条件を満たすファイルのバッチアップロード」をご参照ください。
--meta	ファイルのメタデータ。これには、標準 HTTP ヘッダーと、`x-oss-meta-` で始まるユーザー定義メタデータが含まれます。メタデータは `header:value#header:value` 形式である必要があります。例：`Cache-Control:no-cache#Content-Encoding:gzip`。OSS がサポートするメタデータの詳細については、「オブジェクトメタデータの管理」をご参照ください。
--acl	ファイルのアクセス制御リスト (ACL)。有効値： default (デフォルト)：オブジェクトの ACL はバケットの ACL と同じです。 private：バケットのオーナーのみがバケット内のオブジェクトを読み書きできます。他のユーザーはオブジェクトにアクセスできません。 public-read：バケットのオーナーのみがバケット内のオブジェクトに書き込みできます。匿名ユーザーを含む他のユーザーはオブジェクトを読み取ることができます。これにより、データ漏洩や予期せぬ高額な料金が発生する可能性があります。悪意のあるユーザーがオブジェクトに違法な情報を書き込んだ場合、お客様の正当な権利と利益が侵害される可能性があります。特別なシナリオを除き、この権限を設定しないでください。 public-read-write：匿名ユーザーを含む誰でもバケット内のオブジェクトを読み書きできます。これにより、データ漏洩や予期せぬ高額な料金が発生する可能性があります。この権限を設定する際は注意してください。
--snapshot-path	アップロードされたファイルのスナップショット情報を保存するディレクトリ。次回のアップロード時に、ossutil は指定されたディレクトリからスナップショット情報を読み取り、増分アップロードを実行します。
--disable-crc64	64 ビット巡回冗長検査 (CRC-64) データ検証を無効にします。デフォルトでは、ossutil はデータ転送のために CRC-64 検証を有効にします。
--disable-dir-object	ファイルをアップロードする際に、ディレクトリのオブジェクトを生成しません。
--payer	リクエストの支払方法。指定されたパスへのアクセスによって生成されるトラフィック、リクエスト、およびその他のリソースの料金をリクエスタに支払わせたい場合は、このオプションを requester に設定します。
--tagging	アップロード中にオブジェクトに追加するタグ。フォーマットは `TagkeyA=TagvalueA&TagkeyB=TagvalueB....` です。
-j，--jobs	複数ファイルに対する操作の同時タスク数。デフォルト値は 3 です。有効値：1～10000。
--parallel	単一ファイルに対する操作の同時タスク数。有効値：1～10000。このオプションを設定しない場合、ossutil は操作の種類とファイルサイズに基づいて値を決定します。
--start-time	UNIX タイムスタンプ。この時刻より前に最終更新されたオブジェクトは無視されます。説明 ossutil 1.7.18 以降のみがこのパラメーターをサポートしています。アップグレードの詳細については、「update (ossutil のアップグレード)」をご参照ください。
--end-time	UNIX タイムスタンプ。この時刻より後に最終更新されたオブジェクトは無視されます。説明 `start-time` と `end-time` の両方を指定した場合、copy コマンドは指定された開始時刻と終了時刻の間に最終更新されたファイルに対してのみ実行されます。 ossutil 1.7.18 以降のみがこのパラメーターをサポートしています。バージョンのアップグレード方法の詳細については、「update (ossutil のアップグレード)」をご参照ください。

このコマンドの他の共通オプションの詳細については、「共通オプション」をご参照ください。

デフォルトの同時タスク数がパフォーマンス要件を満たさない場合は、-j, --jobs および --parallel オプションを調整できます。デフォルトでは、ossutil はファイルサイズに基づいて `parallel` オプションの値を計算します。大容量ファイルをバッチで転送する場合、実際の同時タスク数は `jobs` オプションの値に `parallel` オプションの値を掛けたものになります。

コマンドを実行する ECS インスタンスまたはサーバーのリソース (ネットワーク帯域幅、メモリ、CPU など) が限られている場合は、同時タスク数を 100 以下などの値に減らすことができます。リソースが完全に使用されていない場合は、同時タスク数を増やすことができます。
同時タスク数が多すぎると、スレッド切り替えのオーバーヘッドやリソース競合によりパフォーマンスが低下する可能性があります。これにより、EOF エラーが発生することさえあります。お使いのマシンの実際のリソースに基づいて -j, --jobs および --parallel オプションを調整してください。ストレステストを実行する際は、低い同時タスク数から始めて、徐々に数を増やして最適な値を見つけてください。

例

以下の例は Linux システムで実行されます。お使いのオペレーティングシステムと実際の環境に基づいてパラメーターを変更する必要があります。例では、次の規則が使用されます。

バケット名：examplebucket
OSS ディレクトリ：desfolder/
ローカルディレクトリ：localfolder/
ローカルファイル：examplefile.txt

単一ファイルのアップロード

ファイルを指定のディレクトリにアップロードし、元のファイル名をオブジェクト名として使用します。OSS でオブジェクト名を指定しない場合、デフォルトで元のファイル名が使用されます。名前を指定した場合、オブジェクトはその名前で OSS に保存されます。
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```
単一ファイルをアップロードし、--meta オプションを使用してファイルのメタデータを設定します。メタデータは header:value#header:value... 形式である必要があります。
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
```

バッチアップロード

フォルダ内のファイルのみをアップロード
-r オプションを cp コマンドに追加して、ローカルフォルダから OSS の指定パスにファイルのみをアップロードします。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/
```
指定した時間範囲内のフォルダからファイルをアップロード
ローカルフォルダから指定した OSS パスにファイルをアップロードします。ファイルは 2023 年 10 月 31 日 10:09:18 (UTC+08:00) から 2023 年 10 月 31 日 12:55:58 (UTC+08:00) の間に変更されている必要があります。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
```
フォルダとそのファイルをアップロード
-r オプションを指定した cp コマンドを使用して、ローカルフォルダとそのファイルを指定した OSS パスにアップロードします。各サブディレクトリに対して、OSS はスラッシュ (/) で終わる対応する 0 KB のオブジェクトを作成します。ただし、OSS は指定されたフォルダに対応するオブジェクトを作成しません。フォルダのオブジェクトを作成するには、mkdir (ディレクトリの作成) コマンドを使用できます。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
```
既存のファイルをスキップしてフォルダをアップロード
失敗したバッチアップロードをリトライする際に、--update (または -u) オプションを指定して、正常にアップロードされたファイルをスキップし、増分アップロードを実行できます。例：
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```
現在のディレクトリ内のファイルのみをアップロードし、サブディレクトリを無視
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r
```
ディレクトリオブジェクトを作成せずにアップロード
OSS では、ディレクトリは名前がスラッシュ (/) で終わる 0 KB のオブジェクトで表されます。ディレクトリをアップロードする際に、--disable-dir-object パラメーターを追加できます。このパラメーターを追加すると、ossutil はディレクトリのオブジェクトを作成しませんが、OSS コンソールで対応するディレクトリ構造を確認できます。ディレクトリ内のすべてのファイルを削除すると、ディレクトリも削除されます。
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
```
リンクされたサブディレクトリ内のファイルをアップロード
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r
```
アップロード中にすべてのリンクされたサブファイルとリンクされたサブディレクトリを無視
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink
```

指定された条件を満たすファイルのバッチアップロード

ファイルをバッチでアップロードする際に、--include および --exclude オプションを指定して、指定された条件を満たすファイルのみをアップロードできます。

--include および --exclude オプションは、次のフォーマットをサポートしています。

アスタリスク (*): 任意の数の文字に一致します。たとえば、*.txt はすべての TXT ファイルに一致します。
疑問符 (?): 1 文字に一致します。たとえば、abc?.jpg は、abc1.jpg のように、名前が "abc" の後に 1 文字が続くすべての JPG ファイルに一致します。
[sequence]: シーケンス内の任意の文字に一致します。たとえば、abc[1-5].jpg は、abc1.jpg から abc5.jpg という名前のファイルに一致します。
[!sequence]: シーケンス外の任意の文字に一致します。たとえば、abc[!0-7].jpg は、名前が abc0.jpg から abc7.jpg ではないファイルに一致します。

1 つのルールに複数の include および exclude 条件を含めることができます。ossutil は、各ファイルを左から右へ条件と照合し、ファイルを含めるか除外するかを決定します。たとえば、test.txt という名前のファイルを含むフォルダを考えてみましょう。異なる照合ルールは次の結果を生成します。

ルール 1: --include "*test*" --exclude "*.txt" 。ルールが --include "*test*" に一致すると、結果は test.txt が条件を満たすことになります。ルールが --exclude "*.txt" に一致し続けると、test.txt はファイル名に .txt が含まれているため除外されます。最終的な結果は、test.txt がアップロードされないことです。
ルール 2: --exclude "*.txt" --include "*test*"。ファイル test.txt は、まず --exclude "*.txt" ルールによって除外されます。しかし、その後の --include "*test*" ルールは、ファイル名に "test" が含まれているため test.txt を含めます。結果として、test.txt はアップロードされます。
ルール 3: --include "*test*" --exclude "*.txt" --include "te?t.txt" 。まず、--include "*test*" ルールが test.txt を含めます。次に、--exclude "*.txt" ルールが test.txt を除外します。最後に、--include "te?t.txt" ルールが再び test.txt を含めます。したがって、test.txt はアップロードされます。

重要

条件にディレクトリ形式を指定することはできません。たとえば、--include "/usr/test/.jpg" はサポートされていません。

以下に例を示します。

TXT 形式のすべてのファイルをアップロード

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r

名前に abc を含み、JPG または TXT 形式ではないすべてのファイルをアップロード

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

アップロードの調整

ファイルをアップロードする際に、--maxupspeed オプションを使用して最大アップロード速度を KB/s 単位で制限できます。以下に例を示します。

ファイルをアップロードし、速度制限を 1 MB/s に設定

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024

フォルダをアップロードし、速度制限を 1 MB/s に設定

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

オブジェクトタグのアップロードと設定

ファイルをアップロードする際に、--tagging オプションを使用してオブジェクトタグを設定できます。複数のタグはアンパサンド (&) で区切ります。以下に例を示します。

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&……"

オブジェクトタグ付けの詳細については、「オブジェクトタグ付け」をご参照ください。

ストレージクラスのアップロードと指定

ファイルをアップロードする際に、--meta オプションを使用してそのストレージクラスを設定できます。有効値は次のとおりです。

Standard: 標準
IA: 低頻度アクセス
Archive: アーカイブストレージ
ColdArchive: コールドアーカイブ
DeepColdArchive: ディープコールドアーカイブ

アップロード中にストレージクラスを指定しない場合、オブジェクトはバケットのストレージクラスを継承します。詳細については、「ストレージクラス」をご参照ください。

ファイルをアップロードしてストレージクラスを指定する例を次に示します。

単一ファイルをアップロードし、そのストレージクラスを低頻度アクセスに設定
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA
```
フォルダをアップロードし、そのファイルのストレージクラスを標準に設定
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r
```

ACL のアップロードと指定

ファイルをアップロードする際に、--acl オプションを使用してそのアクセス制御リスト (ACL) を設定できます。ファイル ACL の有効値は次のとおりです。

default: バケットの ACL を継承 (デフォルト)
private: 非公開
public-read: 公開読み取り
public-read-write: 公開読み書き

以下に例を示します。

単一ファイルをアップロードし、その ACL を非公開に設定
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private
```
フォルダをアップロードし、フォルダ内のファイルの ACL を公開読み取りに設定する
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r
```

暗号化方式のアップロードと指定

ファイルをアップロードする際に、サーバーサイド暗号化方式を指定して、バケットに保存する前にファイルを暗号化できます。以下に例を示します。

ファイルをアップロードし、暗号化方式として SSE-OSS を、暗号化アルゴリズムとして AES256 を指定
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256
```
ファイルをアップロードし、暗号化方式として SSE-KMS を指定し、CMK ID を指定しない
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS
```
KMS 暗号化を使用する場合、KMS キーの使用に対して少額の料金が請求されます。詳細については、「KMS の料金」をご参照ください。

ファイルをアップロードし、暗号化方式として SSE-KMS と CMK ID を指定

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

サーバーサイド暗号化の詳細については、「サーバーサイド暗号化」をご参照ください。

スナップショットのアップロードと生成

ファイルをバッチでアップロードする際に、--snapshot-path オプションを指定すると、ossutil は指定されたディレクトリにファイルアップロードの進捗のスナップショットを生成します。スナップショットは、正常にアップロードされたローカルファイルの `lastModifiedTime` を記録します。次回のアップロード時に、ossutil は `lastModifiedTime` を比較してファイルをスキップするかどうかを判断します。したがって、このオプションを使用する場合は、2 回のアップロードの間に他のユーザーが OSS 内の対応するオブジェクトを変更しないことを確認する必要があります。--snapshot-path オプションは、増分アップロードを高速化するのに適しています。以下に例を示します。

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path

重要

ossutil は snapshot-path ディレクトリ内のスナップショット情報を自動的に削除しません。スナップショット情報が大きくなりすぎるのを防ぐために、snapshot-path ディレクトリから不要なスナップショットを定期的に削除する必要があります。
スナップショット情報の読み書きには追加のオーバーヘッドが発生します。バッチでアップロードするファイル数が少ない場合、ネットワーク状態が良い場合、または他のユーザーが同じオブジェクトを操作している場合は、このオプションを使用しないでください。これらのシナリオでは、増分アップロードに --update オプションを使用できます。
--update と --snapshot-path オプションを同時に使用できます。ossutil はまず `snapshot-path` 情報をチェックしてファイルをスキップするかどうかを判断します。スナップショットに基づいてファイルがスキップされない場合、ossutil は次に --update オプションを使用してファイルをスキップするかどうかを判断します。

リクエスト元による支払いのアップロードと設定

ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester

クロスアカウントまたはクロスリージョンのアップロード

-e、-i、-k 共通オプションを使用して、ローカルファイル exampleobject.txt を examplebucket バケットの desfolder/ ディレクトリにアップロードします。このバケットは中国 (上海) リージョンにあり、別の Alibaba Cloud アカウントが所有しています。

説明

バケットがあるリージョンに対応するエンドポイントを指定する必要があります。詳細については、「リージョンとエンドポイント」をご参照ください。

ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret