上传文件 - 对象存储 OSS

您可以通过cp命令将您本地的文件上传至OSS。

注意

使用cp命令上传文件时，默认使用分片上传和断点续传。若您因意外中断了文件上传的过程，且未继续完成该文件的上传，则已上传的部分会以碎片（Part）的形式存储在OSS的存储空间（Bucket）中。若您不再需要这些Part，建议您通过以下方式删除，以免产生额外的存储费用。
- 手动删除Part，请参见删除碎片。
- 通过生命周期规则自动删除Part，请参见设置生命周期规则。
cp命令的格式、支持的参数请参见简介。

示例环境

本文以Linux系统为例，将本地文件或文件夹上传至OSS中。您在实际使用中，请根据您的系统和使用环境修改对应参数。本文涉及的所有通用示例说明如下：

本地文件：examplefile.txt（根目录下的文件）
本地文件夹：localfolder（根目录下的文件夹）
目标Bucket：examplebucket
目标Bucket指定目录：desfolder

简单上传示例

ossutil支持将本地文件上传到OSS，命令如下：

上传单个文件
上传时，若不指定上传至OSS的文件名，则默认使用原文件名；若指定文件名，则按照指定的文件名保存在OSS中。
```
./ossutil cp examplefile.txt oss://examplebucket/desfolder/
```
上传文件夹
使用cp命令时增加-r选项，可以将目标文件夹上传到OSS。
```
./ossutil cp -r localfolder/ oss://examplebucket/desfolder/
```
说明若上传的符号链接（软链接）且指向本地文件夹，使用cp命令上传时，应当给软链接加上正斜线（/）。例如：
```
./ossutil cp -r symbolic_link/ oss://examplebucket/desfolder/
```
上传单个文件并指定--meta选项
上传文件的同时可以使用--meta选项设置文件的meta信息，其内容格式为header:value#header:value...。
```
./ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
```
说明更多关于meta设置的信息请参见set-meta。
上传文件夹并跳过已有文件
批量上传失败重传时，可以指定--update（可缩写为-u）选项跳过已经上传成功的文件，实现增量上传。命令如下：
```
./ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

上传文件到开通了请求者付费模式的Bucket

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

./ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r

上传时不为目录生成Object
OSS的目录是用一个0 KB大小，名称以正斜线（/）结尾的Object模拟的。上传时增加--disable-dir-object参数，ossutil不会为该目录生成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

上传时限速

您可以在上传文件时，指定--maxupspeed选项，设置上传的最高速度，单位为KB/s，缺省为0（不限速）。命令如下：

上传文件并设置限速为1 MByte/s

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

上传文件夹并设置限速为1 MByte/s

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

上传并设置对象标签

您可以在上传文件时，通过--tagging选项设置文件对象标签，多个标签以and（&）符号隔开。命令如下：

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

关于对象标签的更多说明请参见object-tagging。

上传并指定文件类型

您可以在上传文件时，通过--meta选项设置文件存储类型。存储类型可选值为：

Standard：标准存储
IA：低频访问
Archive：归档存储

若上传时未指定存储类型，则以存储空间的存储类型为准。更多详情请参见存储类型介绍。命令如下：

上传单个文件并指定存储类型为低频访问类型

./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

您可以在上传文件时，通过--meta选项设置文件的ACL。文件ACL可选值为：

default：继承Bucket（默认）
private：私有
public-read：公共读
public-read-write：公共读写

命令如下：

上传单个文件并指定ACL为私有

./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta x-oss-object-acl:private

上传文件夹并指定ACL为公共读

./ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta x-oss-object-acl:public-read  -r

上传并指定加密方式

您可以在上传文件时指定文件的服务器端加密方式，将文件加密后保存在Bucket内，关于服务器端加密功能介绍请参见服务器端加密。命令如下：

上传文件并指定加密方式为OSS完全托管，加密算法为AES256

./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256

上传文件并指定加密方式为OSS完全托管，加密算法为SM4

./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:SM4

上传文件并指定加密方式为KMS，指定加密算法为AES256，不指定CMK ID
```
./ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS
```
使用KMS加密时，会产生少量KMS密钥使用费用，详情请参见KMS计费标准。

上传文件并指定加密方式为KMS，指定加密算法为SM4，指定CMK ID

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

上传并生成快照

批量上传时，若指定--snapshot-path选项，ossutil在指定的目录下生成文件上传的快照，记录成功上传、下载的文件的本地lastModifiedTime，在下次上传、下载时通过比较lastModifiedTime来决定是否跳过相同文件，所以在使用该选项时，请确保两次上传、下载期间没有其他用户更改了OSS上的对应Object。--snapshot-path选项用于在某些场景下加速增量上传、下载批量文件（拷贝不支持该选项）。命令如下：

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

注意

ossutil不会主动删除snapshot-path文件夹中的快照信息。为避免快照信息过多，请定期删除snapshot-path文件夹内无用的快照。
由于读写snapshot信息需要额外开销，当要批量上传、下载的文件数比较少或网络状况比较好或有其他用户操作相同Object时，并不建议使用该选项。可以使用--update选项来增量上传、下载。
--update选项和--snapshot-path选项可以同时使用，ossutil会优先根据snapshot-path信息判断是否跳过此文件，如果不满足跳过条件，再根据--update判断是否跳过此文件。

批量上传符合条件的文件

批量上传时，若指定--include和--exclude选项，ossutil会批量上传符合指定条件的文件。

--include和--exclude选项支持格式：

通配符星号（*）：匹配所有字符。例如：*.txt表示匹配所有TXT格式的文件。
通配符问号（？）：匹配单个字符。例如：abc?.jpg表示匹配所有文件名为abc+任意单个字符的JPG格式的文件，如abc1.jpg。
[sequence]：匹配序列的任意字符，例如：abc[1-5].jpg表示匹配文件名为abc1.jpg~abc5.jpg的文件。
[!sequence]：匹配序列外的任意字符，例如：abc[!0-7].jpg表示匹配文件名不为abc0.jpg~abc7.jpg的文件。

一条规则中可以包含多个include（包含）和exclude（排除）条件，且每个文件从左到右逐一运用每个规则，直至最后才能最终确定匹配的结果。例如指定生效的文件夹中包含名为test.txt的文件，匹配不同的规则产生的结果如下。

规则一：--include "*test*" --exclude "*.txt" ，当规则匹配到--include "*test*"，匹配的结果为test.txt符合条件；当规则继续匹配到--exclude "*.txt"时，因test.txt文件名包含.txt，所以被排除。则匹配的最终结果为test.txt不符合条件。
规则二：--exclude "*.txt" --include "*test*"，当规则匹配到--exclude "*.txt"，匹配的结果为test.txt不符合条件；当规则继续匹配到--include "*test*"，因test.txt文件名包含test，所以符合条件。则匹配的最终结果为test.txt符合条件。
规则三：--include "*test*" --exclude "*.txt" --include "te?t.txt" ，当规则匹配到--include "*test*"，匹配的结果为test.txt符合条件；当规则继续匹配到--exclude "*.txt"时，因test.txt文件名包含.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