# 上传对象 #### 功能说明 上传单个或多个本地文件或文件夹至OBS指定路径。待上传的文件可以是任何类型：文本文件、图片、视频等等。 ![](https://support.huaweicloud.com/utiltg-obs/public_sys-resources/notice_3.0-zh-cn.png) 上传本地文件或文件夹时，请确保本地文件或文件夹在上传过程不发生变化，否则可能产生上传失败或者数据不一致的问题。 #### 约束与限制 obsutil对上传的文件或文件夹有大小限制，最小可以上传**0Byte** 的空文件或文件夹，最大可以上传**5GB** （未采用分段上传）或**48.8TB**（采用分段上传）的单个文件。 #### 前提条件 在执行上传对象操作前，请确保您已经[下载并安装obsutil](https://support.huaweicloud.com/utiltg-obs/obs_11_0003.html)。 #### 命令结构 - Windows操作系统 - 上传文件 ``` obsutil cp file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-encoding-type=url] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx] ``` - 上传文件夹 ``` obsutil cp folder_url obs://bucket[/key] -r [-arcDir=xxx] [-dryRun] [-link] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-encoding-type=url] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx] ``` - 多文件/文件夹上传 ``` obsutil cp file1_url,folder1_url|filelist_url obs://bucket[/prefix] -msm=1 [-r] [-arcDir=xxx] [-dryRun] [-link] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-encoding-type=url] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx][-timeRange=time1-time2] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx] ``` ![](https://support.huaweicloud.com/utiltg-obs/public_sys-resources/note_3.0-zh-cn.png) 命令中的"/prefix"即为上传文件夹时的对象名前缀。运行示例请参见[上传示例](https://support.huaweicloud.com/utiltg-obs/obs_11_0028.html)。 - Linux/Mac操作系统 - 上传文件 ``` ./obsutil cp file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx] ``` - 上传文件夹 ``` ./obsutil cp folder_url obs://bucket[/key] -r [-arcDir=xxx] [-dryRun] [-link] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx] ``` - 多文件/文件夹上传 ``` ./obsutil cp file1_url,folder1_url|filelist_url obs://bucket[/prefix] -msm=1 [-r] [-arcDir=xxx] [-dryRun] [-link] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx][-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx] ``` ![](https://support.huaweicloud.com/utiltg-obs/public_sys-resources/note_3.0-zh-cn.png) 命令中的"/prefix"即为上传文件夹时的对象名前缀。运行示例请参见[上传示例](https://support.huaweicloud.com/utiltg-obs/obs_11_0028.html)。 #### 运行示例 - 以Windows操作系统为例，运行**obsutil cp d:\\temp\\test.txt obs://bucket-test/key** ，将D盘temp路径下名为test.txt的文件上传至bucket-test桶中，并且重命名为key。 ``` obsutil cp d:\temp\test.txt obs://bucket-test/key Start at 2024-09-30 08:11:41.6724827 +0000 UTC Parallel: 5 Jobs: 5 Threshold: 50.00MB PartSize: auto VerifyLength: false VerifyMd5: false CheckpointDir: C:\Users\Administrator\.obsutil_checkpoint [====================================================] 100.00% 1.68 MB/s 8.46MB/8.46MB 5s Upload successfully, 8.46MB, n/a, d:\temp\test.txt --> obs://bucket-test/key, cost [5], status [200], request id [0000016979E1D2B2860BB5181229C72C] ``` - 以Windows操作系统为例，运行**obsutil cp d:\\temp obs://bucket-test -f -r** ，递归上传D盘temp文件夹中的所有文件和子文件夹至bucket-test桶的temp文件夹中。 ``` obsutil cp d:\temp obs://bucket-test -f -r Start at 2024-09-30 08:14:12.1406275 +0000 UTC Parallel: 5 Jobs: 5 Threshold: 50.00MB PartSize: auto VerifyLength: false VerifyMd5: false CheckpointDir: C:\Users\Administrator\.obsutil_checkpoint Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed OutputDir: C:\Users\Administrator\.obsutil_output [========================================================] 100.00% tps:35.71 2.02 KB/s 7.20MB/7.20MB 0s Succeed count: 5 Failed count: 0 Succeed bytes: xxx Metrics [max cost:90 ms, min cost:45 ms, average cost:63.80 ms, average tps:35.71, transferred size: 7.20MB] Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed ``` - 更多运行示例，请参见[常见示例](https://support.huaweicloud.com/utiltg-obs/obs_11_0027.html)。 #### 参数说明 | **参数** | **约束** | **描述** | |:---|:---|:---| | file_url | 多文件/文件夹上传时可选 上传文件时必选 | 本地文件路径。 - 多文件/文件夹上传时，禁止路径嵌套，例如：/a/b/c和/a/b/。 - 多文件/文件夹上传时，必须配置msm=1，此时可以用英文逗号分隔多个文件，例如：file_url1,file_url2。 - 多文件/文件夹上传时，文件和文件夹可以同时存在，例如：file_url1,folder_url1,file_url2,folder_url2。 | | folder_url | 多文件/文件夹上传时可选 上传文件夹时必选 | 本地文件夹路径。 - 上传文件夹时，如果未设置flat选项，则直接上传整个文件夹；如果设置了flat选项，则上传文件夹下的所有内容。 - 多文件/文件夹上传时，禁止路径嵌套，例如：/a/b/c和/a/b/。 - 多文件/文件夹上传时，必须配置msm=1，此时可以用逗号分隔多个文件夹，例如：folder_url1,folder_url2。 - 多文件/文件夹上传时，文件和文件夹可以同时存在，例如：file_url1,folder_url1,file_url2,folder_url2。 | | filelist_url | 多文件/文件夹上传时可选 | 包含待上传文件/文件夹列表的文件，必须配置msm=2。 - 该文件为普通文本文件（如.txt文件、.csv文件），文件中的每行代表一个待上传的文件/文件夹，例如： file_url1 file_url2 folder_url1 folder_url2 - 文件中待上传的文件/文件夹禁止路径嵌套，例如：/a/b/c和/a/b/。 | | bucket | 必选 | 上传文件/文件夹所属的桶的名称。 | | key | 可选 | 上传文件时的对象名或对象名前缀，或上传文件夹时的对象名前缀。 在上传文件或文件夹时，根据指定值的不同情况，对象的上传路径和名称如下： - 如果该值为空：对象将上传到桶的根目录（存储桶的顶级目录），对象名将使用所上传文件或文件夹的名称。 - 如果该值不为空： - 如果该值以"/"结尾：对象将上传到该值指定的目录下，对象名将为"该值+文件名"，如：folder/filename.txt和folder/foldername。 - 如果该值不以"/"结尾：对于文件，其名称将直接使用该值，如：filename.txt；对于文件夹，将上传到以该值加上"/"结尾的目录下。如：folder/。 说明： 您还可以参考[上传示例](https://support.huaweicloud.com/utiltg-obs/obs_11_0028.html)理解该参数的使用方式。 | | fr | 附加参数，上传文件时可选 | 上传文件时生成结果清单文件。 | | flat | 附加参数，多文件/文件夹上传或上传文件夹时可选 | 上传文件夹时，只上传该文件夹下的所有内容。 | | arcDir | 附加参数，可选 | 上传文件成功后的归档路径，上传成功后的文件会移动到该路径下。 | | dryRun | 附加参数，可选 | 测试模式运行，不执行实际的上传操作。 | | link | 附加参数，可选 | 上传软链接文件/文件夹指向的真实路径。 - 如果未指定该参数，而待上传的文件是一个软链接且该软链接指向的目标文件不存在，则Windows操作系统会产生"The system cannot find the file specified"的上传失败异常，而macOS/Linux操作系统会产生"No such file or directory"的上传失败异常。 - 文件夹软链接不能形成环，否则上传会以panic的形式退出；如果不希望产生panic，请在配置文件中配置panicForSymbolicLinkCircle为false。 | | u | 附加参数，可选 | 增量上传操作。 设置该参数后，上传每个文件时会对比桶中对应路径的对象，仅在对象不存在，或者对象大小与所上传文件大小不一致，或者对象的最后修改时间早于所上传文件的最后修改时间时进行上传。 **在比较每个本地文件与桶内对象差异时，会产生一次HEAD[请求费用](https://support.huaweicloud.com/price-obs/obs_42_0004.html)。** 说明： 该参数可以与-last-modify-only搭配使用，具体效果查看-last-modify-only的描述说明。 | | -last-modify-only | 附加参数，可选 | 对比逻辑仅比较目标对象是否存在和对象的修改时间，并针对最后更新的对象进行增量操作。 说明： 该参数与-u搭配使用，单独使用并不生效。 | | vlength | 附加参数，可选 | 上传完成后，验证桶中对象的大小是否与本地文件大小一致。 | | vmd5 | 附加参数，可选 | 上传完成后，验证桶中对象的MD5值是否与本地文件的MD5值一致。 - **如果您的业务涉及加密场景，请勿使用该参数。** - 如果待上传的本地文件较大，使用该参数将会因为计算MD5而导致整体性能下降。 - MD5值校验通过后，会将该值设置为对象元数据**x-obs-meta-md5chksum** ，用于下载或复制时校验MD5。了解更多请参见[基于crc64或MD5的OBS数据完整性校验](https://support.huaweicloud.com/bestpractice-obs/obs_05_0801.html)，了解几种数据校验方式的区别请参见[几种校验对象数据完整性的方式](https://support.huaweicloud.com/usermanual-obs/obs_41_0015.html)。 | | p | 附加参数，可选 | 每个分段上传任务的最大并发数。 默认为配置文件中的defaultParallels。 | | threshold | 附加参数，可选 | 开启分段上传任务的阈值。如果待上传的文件小于该阈值，则使用直接上传模式；否则使用分段上传模式。 默认为配置文件中的defaultBigfileThreshold。 单位：字节 支持带容量单位配置，例如：配置1MB代表1048576字节。 说明： 直接上传模式不会产生断点记录文件，不支持断点续传。 | | acl | 附加参数，可选 | 上传文件时可指定对象的预定义访问策略。 支持的值： - private：私有读写，除对象ACL授权外的其他用户无对象的访问权限。 - public-read：公共读，任何用户都可以对桶内对象进行读操作。 - public-read-write：公共读写，任何用户都可以对桶内对象进行读/写/删除操作。 - bucket-owner-full-control：桶拥有者完全控制，其他任何人都没有访问权限。 | | sc | 附加参数，可选 | 上传文件时可指定的对象的存储类型。 支持的值： - standard：标准存储，访问时延低、吞吐量高，适用于有大量热点文件（平均一个月多次）或小文件（小于1MB）。 - warm：低频访问存储，可用性略低于standard，适用于不频繁访问（平均一年少于12次）但在需要时也要求快速访问数据的业务场景。 - cold：归档存储，安全、持久且成本极低，适用于很少访问（平均一年访问一次）数据的业务场景。 - deep-archive：深度归档存储，适用于长期不访问（平均几年访问一次）数据的业务场景，其成本相比归档存储更低，但相应的数据恢复时间将更长，一般为数小时。 | | meta | 附加参数，可选 | 上传文件时可指定的标准和自定义元数据。 - 标准元数据包括：Content-Type、Content-Encoding、Cache-Control、Content-Disposition、Content-Language、Expires。 - 自定义元数据格式为：key:value，多个自定义元数据使用#链接。例如key1:value1#key2:value2#key3:value3，其含义是，上传文件后，桶内目标对象包含三组自定义元数据，分别为：key1:value1、key2:value2、key3:value3。 | | ps | 附加参数，可选 | 每个分段上传任务的段大小。 - 默认为配置文件中的defaultPartSize，支持配置为auto，此时obsutil会根据源文件大小自动设置每个分段任务的段大小。 - 取值范围：100KB\~5GB - 单位：字节。支持带容量单位配置，例如，配置1MB代表1048576字节。 | | cpd | 附加参数，可选 | 生成断点记录文件的文件夹，默认为运行obsutil命令的用户目录的子文件夹.obsutil_checkpoint。 每个分段上传任务会产生唯一对应的断点记录文件并保存至该文件夹的upload子文件夹下。分段任务执行成功后，对应的断点记录文件会被自动删除；分段任务执行失败或被中断后，下次执行该分段任务时会尝试通过对应的断点记录文件恢复任务。 | | r | 附加参数，上传文件夹时必选 多文件上传时可选 | 递归上传文件夹中的所有文件和子文件夹。 | | f | 附加参数，多文件/文件夹上传或上传文件夹时可选 | 强制操作，不进行询问提示。 | | j | 附加参数，多文件/文件夹上传或上传文件夹时可选 | 上传文件夹时批量任务的最大并发数，默认为配置文件中的defaultJobs。 说明： 工具会保证该值至少为1。 | | encoding-type | 附加参数，可选 | 对象名有特殊字符时，取值为url。 Util 5.5.12版本及以上支持该参数。 | | msm | 附加参数，多文件/文件夹上传时必选 | 开启多文件/文件夹上传模式，支持的值：\[1\|2\]。 - 如果msm=1，则代表上传的URL是一组文件/文件夹列表（以英文逗号分隔）。 - 如果msm=2，则代表上传的URL是一个包含文件/文件夹列表的文件。 - 如果文件/文件夹名本身包含英文逗号，请不要使用"msm=1"的模式。 - 如果没有设置r参数，则列表中的文件夹不会被上传。 | | exclude | 附加参数，多文件/文件夹上传或上传文件夹时可选 | 不包含文件的匹配模式，设置该参数后，如果待上传的文件名匹配该参数，则跳过该文件的上传。如：\*.txt，代表所有后缀为.txt的文件自动跳过，不上传。 - "\*"匹配多个任意字符，如："abc\*.txt"表示匹配所有以"abc"开头，中间可以包含任意数量的任意字符，以".txt"结尾的文件名。 - "?"匹配单个任意字符，如："abc?.txt"表示匹配所有以"abc"开头，中间包含1个任意字符，以".txt"结尾的文件名。 - 您可以使用"\\\*"代表匹配"\*"字符本身，使用"\\?"代表匹配"?"字符本身。 - 支持指定多个exclude参数，如 -exclude=\*.xxx -exclude=\*.xxx **约束限制：** 该匹配模式仅对文件夹中的文件生效。 说明： - 建议使用引号传递该匹配模式（Linux/Mac操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。 - 该匹配模式作用于文件全路径（含文件名和文件目录）。 | | include | 附加参数，多文件/文件夹上传或上传文件夹时可选 | 包含文件的匹配模式，设置该参数后，如果待上传的文件名匹配该参数，则上传该文件。如：\*.txt，代表所有后缀为.txt的文件将会被上传。 - "\*"匹配多个任意字符，如："abc\*.txt"表示匹配所有以"abc"开头，中间可以包含任意数量的任意字符，以".txt"结尾的文件名。 - "?"匹配单个任意字符，如："abc?.txt"表示匹配所有以"abc"开头，中间包含1个任意字符，以".txt"结尾的文件名。 - 您可以使用"\\\*"代表匹配"\*"字符本身，使用"\\?"代表匹配"?"字符本身。 - 支持指定多个include参数，如 -include=\*.xxx -include=\*.xxx **约束限制：** - 该匹配模式仅对文件夹中的文件生效。 - 如果同时配置了exclude和include参数，则首先执行exclude的匹配规则，如果待上传的文件名不匹配exclude参数，则判断待上传的文件名是否匹配include参数，如果匹配则上传该文件，否则跳过该文件的上传。 **示例：** ``` ./obsutil cp /localpath/ obs://test/ -include=/localpath/2022-12-09/* -f -r ``` 以上命令的含义是：上传本地路径localpath下符合匹配规则的文件到test桶下，匹配规则是以"/localpath/2022-12-09/"开头的。 说明： - 建议使用引号传递该匹配模式（Linux/Mac操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。 - 该匹配模式作用于文件全路径（含文件名和文件目录）。 | | at | 附加参数，多文件/文件夹上传或上传文件夹时可选 | 指定按照文件最后访问时间作为timeRange匹配模式，仅上传最后访问时间满足timeRange时间段的文件。 该参数需配合timeRange参数使用。 | | disableDirObject | 附加参数，多文件夹上传时可选 | 上传文件夹时，文件夹本身不会作为一个单独的对象上传，因此在有很多空文件夹的情况下，可以避免无用的文件夹上传到对象存储桶中。如果文件夹下有文件，这些文件会按原有路径格式上传，文件夹结构不受影响。 | | timeRange | 附加参数，多文件/文件夹上传或上传文件夹时可选 | 上传文件时的时间段匹配模式，仅上传最后修改时间在该时间段内的文件。 该匹配模式优先级低于文件名匹配模式：exclude和include，即优先执行exclude和include参数匹配，然后执行该匹配模式。 - 该匹配模式表示的时间是UTC时间。 - 使用"time1-time2"，代表匹配的时间段，其中time1必须小于等于time2，格式为yyyyMMddHHmmss。 - 时间格式支持自动补全，例如：yyyyMMdd等价于yyyyMMdd000000，yyyyMM等价于yyyyMM01000000。 - 使用"\*-time2"，代表匹配最后修改时间在time2之前的所有文件，使用"time1-\*"，代表匹配最后修改时间time1之后的所有文件。 | | mf | 附加参数，可选 | 设置名称匹配模式（include、exclude）和时间匹配模式（timeRange）对文件夹也生效。 | | o | 附加参数，可选 | 生成结果清单文件的文件夹，命令执行完成后，会在该文件夹下生成结果清单文件（可能包含成功结果、失败结果、警告结果三个文件）。 默认为运行obsutil命令的用户目录的子文件夹.obsutil_output。 - 结果清单文件命名规则：cp_{succeed \| failed \| warning}_report_时间_TaskId.txt。 - 单个结果清单文件默认情况下最大为30MB，可在配置文件中通过recordMaxLogSize分别配置。 - 单个结果清单文件默认情况下最多可保留1024个文件，可在配置文件中通过recordBackups分别配置。 - 当涉及多文件/文件夹时，如需确认失败任务的具体错误信息，可参考结果清单文件夹下的失败结果清单文件"cp_failed_report_时间_TaskId.txt"和日志路径下的[日志文件](https://support.huaweicloud.com/utiltg-obs/obs_11_0056.html)。 | | bucket-cname | 附加参数，可选 | 指定桶绑定的自定义域名 说明： Util 5.7.9版本及以上支持该参数。 | | config | 附加参数，可选 | 运行当前命令时的自定义配置文件。可支持的配置参数请参考[配置参数说明](https://support.huaweicloud.com/utiltg-obs/obs_11_0035.html)。 | | e | 附加参数，可选 | 指定终端节点。 | | i | 附加参数，可选 | 指定用户的AK。 | | k | 附加参数，可选 | 指定用户的SK。 | | t | 附加参数，可选 | 指定用户的securitytoken。 | #### 响应结果 | **字段名** | **描述** | |:---|:---| | Parallel | 请求中的-p参数。 | | Jobs | 请求中的-j参数。 | | Threshold | 请求中的-threshold参数。 | | PartSize | 请求中的-ps参数。 | | Exclude | 请求中的-exclude参数。 | | Include | 请求中的-include参数。 | | TimeRange | 请求中的-timeRange参数。 | | VerifyLength | 请求中的-vlength参数。 | | VerifyMd5 | 请求中的-vmd5参数。 | | CheckpointDir | 请求中的-cpd参数。 | | OutputDir | 请求中的-o参数。 | | ArcDir | 请求中的-arcDir参数。 | | Succeed count | 成功的任务数。 | | Failed count | 失败的任务数。 | | Skip count | 增量上传/下载/复制、同步上传/下载/复制跳过的任务数。 说明： 跳过的任务数也会记录到成功的任务数中。 | | Warning count | 执行完成但包含警告的任务数。 说明： - 产生警告的任务可能是失败的也可能是成功的，需要根据成功或失败的结果清单进一步判断。 - 产生警告的任务数与成功/失败任务数是相互独立的，总任务数仍是成功的任务数+失败的任务数。 | | Succeed bytes | 成功上传的字节数。 | | max cost | 所有任务中的最长耗时，单位：毫秒。 | | min cost | 所有任务中的最短耗时，单位：毫秒。 | | average cost | 平均耗时，单位：毫秒。 | | average tps | 平均每秒的任务完成个数。 | | Task id | 每次运行的唯一标识号，用于查找批量任务生成的结果清单文件。 |