ossutil cp - ファイルとディレクトリを OSS にアップロード - Object Storage Service

cp コマンドを使用して、ローカルファイルまたはディレクトリを OSS バケットにアップロードします。シンプルアップロード、再開可能なアップロード、一括アップロード、増分アップロードをサポートしており、オブジェクトのメタデータ、ストレージクラス、ACL のオプションも指定できます。

仕組み

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

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

注意

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

権限

Alibaba Cloud アカウントは、デフォルトで完全な権限を持っています。 RAM ユーザーおよび RAM ロールにはデフォルトの権限がなく、RAM ポリシーまたはバケットポリシーによる承認が必要です。

API アクション	説明
`oss:PutObject`	オブジェクトをアップロードします。
`oss:PutObjectTagging`	アップロード中にオブジェクトタグを設定する場合にのみ必要です。
`kms:GenerateDataKey`	Key Management Service (KMS) のサーバー側の暗号化を使用する場合にのみ必要です。
`kms:Decrypt`	Key Management Service (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	ファイルとサブディレクトリを再帰的にアップロードします。このオプションがない場合、指定されたファイルのみが処理されます。
-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 に設定すると、ファイル名が 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	CRC-64 データ検証を無効にします。デフォルトで有効です。
--disable-dir-object	アップロード中にディレクトリオブジェクトの作成をスキップします。
--payer	支払い方法。 requester に設定すると、リクエスト元にトラフィックとリクエスト料金が請求されます。
--tagging	アップロード中に追加するタグ。形式：`TagkeyA=TagvalueA&TagkeyB=TagvalueB....`。
-j, --jobs	複数ファイル操作の同時実行タスク数。デフォルト：3。有効な値：1～10000。
--parallel	単一ファイル操作の並列タスク数。有効な値：1～10000。設定されていない場合、操作タイプとファイルサイズに基づいて自動的に決定されます。
--start-time	UNIX タイムスタンプ。この時刻より前に最終更新されたオブジェクトを無視します。説明このパラメーターは ossutil 1.7.18 以降でのみサポートされています。ossutil のアップグレード方法については、「update (ossutil のアップグレード)」をご参照ください。
--end-time	UNIX タイムスタンプ。この時刻より後に最終更新されたオブジェクトを無視します。説明 --start-time と --end-time の両方を指定した場合、指定された開始時刻と終了時刻の間に最終更新されたオブジェクトのみがコピーされます。このパラメーターは ossutil 1.7.18 以降でのみサポートされています。ossutil のアップグレード方法については、「update (ossutil のアップグレード)」をご参照ください。

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

-j, --jobs と --parallel を調整してパフォーマンスをチューニングします。デフォルトでは、ossutil はファイルサイズに基づいて parallel を計算します。大容量ファイルの一括転送の場合、実際の同時実行数は jobs × parallel になります。

マシンのリソース (帯域幅、メモリ、CPU) が限られている場合は、同時実行数を 100 以下に減らしてください。リソースが十分に活用されていない場合は、値を増やしてください。
過剰な同時実行数は、パフォーマンスを低下させたり、EOF エラーを引き起こしたりする可能性があります。マシンのリソースに基づいて -j, --jobs と --parallel を調整してください。低い値から始めて徐々に増やし、最適な値を見つけてください。

例

この例では Linux を使用します。ご使用の OS に合わせてパスを調整してください。この例では、以下を前提としています：

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

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

ファイルをディレクトリにアップロードします。オブジェクト名が指定されていない場合、元のファイル名が使用されます。
```
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+8) から 2023 年 10 月 31 日 12:55:58 (UTC+8) の間に変更されたファイルです。
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
```
フォルダーとその中のファイルをアップロードする

cp -r オプションを使用して、ローカルフォルダーとそのファイルをアップロードします。 OSS は各サブディレクトリに対して / で終わる 0 KB のオブジェクトを作成しますが、フォルダー自体には作成しません。フォルダーオブジェクトを作成するには、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 を使用して、これらのオブジェクトの作成をスキップします。ディレクトリ構造は 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 は、名前が「abc」で始まり、その後に 1 文字が続くすべての JPG ファイル (例：abc1.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" に一致すると、ファイル名に .txt が含まれているため、test.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 を設定します。有効な値：

default：バケットの ACL を継承します (デフォルト)
private：プライベート
public-read：パブリック読み取り
public-read-write：パブリック読み書き

以下に例を示します：

単一ファイルをアップロードし、その ACL を private に設定する
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private
```
フォルダーをアップロードし、そのファイルの ACL を public-read に設定する
```
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 の料金。

ファイルをアップロードし、暗号化方式として 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 を記録し、それを使用して後続のアップロードで変更されていないファイルをスキップし、増分一括アップロードを高速化します。アップロードの間に他のユーザーが対応するオブジェクトを変更しないようにしてください。 --snapshot-path は、大規模な一括アップロードに最適です。例：

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

重要

ossutil は snapshot-path フォルダー内のスナップショットを自動的に削除しません。 snapshot-path フォルダーから不要なスナップショットを定期的に削除してください。
スナップショットの I/O はオーバーヘッドが発生します。小規模なバッチ、良好なネットワーク条件、または共有オブジェクトの場合は、代わりに --update を使用して増分アップロードを行ってください。
--update と --snapshot-path オプションを同時に使用できます。 ossutil はまず snapshot-path 情報をチェックしてファイルをスキップするかどうかを決定します。スナップショットに基づいてファイルがスキップされない場合、ossutil は次に --update オプションを使用してファイルをスキップするかどうかを決定します。

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

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

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

-e、-i、-k の共通オプションを使用して、ローカルファイルを別のリージョンまたは別の Alibaba Cloud アカウントのバケットにアップロードできます。

説明

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

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