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

cp コマンドを使用して、ローカルファイルまたはディレクトリを Object Storage Service (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 と同一になります。プライベート: バケット内のオブジェクトは、所有者のみが読み取りおよび書き込みができます。他のユーザーはオブジェクトにアクセスできません。 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 以降でサポートされています。アップグレードの詳細については、「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
```

バッチアップロード

フォルダー内のファイルのみをアップロードする
ローカルフォルダーのファイルのみを OSS の指定パスにアップロードするには、cp コマンドに -r オプションを追加します。
```
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
```
デフォルトでは、cp コマンドはシンボリックリンクをたどり、シンボリックリンク自体ではなく、そのリンクが指すファイルの内容をアップロードします。

たとえば、link.txt は source.txt を指すシンボリックリンクです：
```
ossutil cp link.txt oss://examplebucket/
```
アップロード後、OSS のオブジェクトコンテンツは source.txt のコンテンツと一致します。この動作は、単一ファイルのアップロードと再帰的なディレクトリのアップロード (-r) でも同様です。

--disable-all-symlink と --enable-symlink-dir オプションは ossutil 1.x でのみ使用可能です。ossutil 2.x では、ossutil はデフォルトでシンボリックリンクをたどり、この動作を無効にするオプションはありません。

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

--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 つのルールに複数のインクルード条件と除外条件を含めることができます。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" ルールによって除外されます。しかし、test.txt はファイル名に "test" が含まれているため、--include "*test*" ルールによって含められます。その結果、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 をプライベートに設定する
```
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 の料金。

ファイルをアップロードし、暗号化方式として 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