文档首页/ 对象存储服务 OBS/ 工具指南（obsutil）（巴黎区域）/ 对象相关命令/ 授权码下载对象
更新时间：2025-02-10 GMT+08:00
查看PDF
分享

授权码下载对象

功能说明

使用授权码下载对象或按对象名前缀批量下载对象到本地。

下载对象或批量下载时，请确保OBS桶中的源对象不发生变化，否则可能产生下载失败或者数据不一致的问题。

命令结构

  • Windows操作系统
    • 直接输入授权码下载单个对象 
      obsutil share-cp authorization_code file_or_folder_url -key=xxx [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-ps=auto] [-cpd=xxx][-fr] [-o=xxx] [-config=xxx]
    • 使用文件路径传入授权码下载单个对象 
      obsutil share-cp file://authorization_code_file_url file_or_folder_url -key=xxx [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-ps=auto] [-cpd=xxx][-fr] [-o=xxx] [-config=xxx]
    • 直接输入授权码批量下载对象 
      obsutil share-cp authorization_code folder_url -r [-key=xxx] [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx]
    • 使用文件路径传入授权码批量下载对象 
      obsutil share-cp file://authorization_code_file_url folder_url -r [-key=xxx] [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx]
  • macOS/Linux操作系统
    • 直接输入授权码下载单个对象 
      ./obsutil share-cp authorization_code file_or_folder_url -key=xxx [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-ps=auto] [-cpd=xxx][-fr] [-o=xxx] [-config=xxx]
    • 使用文件路径传入授权码下载单个对象 
      ./obsutil share-cp file://authorization_code_file_url file_or_folder_url -key=xxx [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-ps=auto] [-cpd=xxx][-fr] [-o=xxx] [-config=xxx]
    • 直接输入授权码批量下载对象 
      ./obsutil share-cp authorization_code folder_url -r [-key=xxx] [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx]
    • 使用文件路径传入授权码批量下载对象 
      ./obsutil share-cp file://authorization_code_file_url folder_url -r [-key=xxx] [-ac=xxx] [-dryRun] [-tempFileDir=xxx] [-f] [-u] [-vlength] [-vmd5] [-flat] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx]

运行示例

  • 以Windows操作系统为例，运行obsutil share-cp xxx d:\temp\test.txt -ac=123456 -key=src/test.txt ，下载单个对象。 
    obsutil share-cp  xxx  d:\temp\test.txt -ac=123456 -key=test/test.txt
The authorized prefix is [test/test.txt]

Start at 2024-09-30 07:55:36.7698045 +0000 UTC

Parallel:      3                   Jobs:          3
Threshold:     50.00MB           PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: xxxx
TempFileDir: xxxx
Waiting to prepare the temp file [xxx].
[==========================================] 100.00% 4.86 KB/s 0s
Download successfully, 19B, n/a, https://endpoint:443/test/test.txt --> d:\temp\test.txt
The authorized prefix is [test/test.txt]
  • 以Windows操作系统为例，运行obsutil share-cp xxx d:\temp -ac=123456 -f -r，批量下载对象。 
    obsutil share-cp xxx d:\temp -ac=123456 -f -r
The authorized prefix is [test]

Start at 2024-09-30 08:05:07.0097508 +0000 UTC

Parallel:      3                   Jobs:          3
Threshold:     50.00MB             PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: xxxx

Task id: 1a50b1dd-3f92-42ae-a974-ff8fe514c2c2
OutputDir: xxxx
TempFileDir: xxxx

[======================================================] 100.00% 155.59 KB/s 0s
Succeed count:   6         Failed count:    0
Succeed bytes: xxx
Metrics [max cost:153 ms, min cost:129 ms, average cost:92.00 ms, average tps:17.86, transferred size:70B]

Task id: 1a50b1dd-3f92-42ae-a974-ff8fe514c2c2
The authorized prefix is [test/]

参数说明

参数

约束

描述

authorization_code

或

file://authorization_code_file_url

必选

授权码。

说明：

如果以“file://”开头，则表明授权码是从本地文件中获取。

file_or_folder_url

下载对象时必选

本地文件/文件夹路径。

folder_url

批量下载时必选

本地文件夹路径。

key

附加参数，下载对象时必选

批量下载时可选

待下载的对象名，或批量下载的对象名前缀。

下载对象时，该值不能为空，最终保存在本地的位置及命名规则如下：

  • 如果file_or_folder_url不存在，则工具会判断其是否以“/”或“\”结尾，如果是，则会以该路径创建文件夹，将对象下载到该新建的文件夹下；
  • 如果file_or_folder_url不存在，且不以“/”或“\”结尾，则以该值作为文件名，将对象下载到本地；
  • 如果file_or_folder_url为已存在的文件，则以该值作为文件名，将对象覆盖下载到本地；
  • 如果file_or_folder_url为已存在的文件夹，则以对象名为文件名，将对象覆盖下载到file_or_folder_url指定的文件夹下。

批量下载时，最终保存在本地的位置规则如下：

  • 如果该值为空，则表示将授权码中授权路径下的所有对象下载到folder_url指定的文件夹下；
  • 如果该值不为空，则将桶内以该值作为对象名前缀的内容下载到folder_url指定的文件夹下。
说明：
  • 如果该值不为空，其必须是授权码中授权路径的子集；
  • 批量下载且该值不为空时，如果未设置flat选项，则下载的本地文件会包含上一级父对象名前缀；如果设置了flat选项，则下载的本地文件不包含上一级父对象名前缀。
须知：

批量下载时，如果设置了flat选项，且如果创建授权码时的对象名前缀为空或者不以“/”结尾，则可能导致下载的对象列表为空。

ac

附加参数，可选

提取码。

说明：
  • 如果未使用该参数设置提取码，obsutil工具会以交互模式提示输入提取码；
  • 提取码必须为6位。

r

附加参数，批量下载时必选

按指定的对象名前缀批量下载对象。

fr

附加参数，下载对象时可选

下载对象时生成结果清单文件。

flat

附加参数，批量下载时可选

批量下载时，不包含上一级父对象名前缀。

tempFileDir

附加参数，可选

分段下载时保存临时文件的文件夹，默认为配置文件中的defaultTempFileDir。

说明：
  • 如果该值为空，且配置文件中的defaultTempFileDir也为空，则分段下载时生成的临时文件会保存在待下载文件的同目录下并以.obs.temp结尾。
  • 由于分段下载时生成的临时文件会保存在该目录，请确保运行obsutil的用户对该路径有写权限；
  • 该路径的可用空间需要大于待下载对象的大小。

dryRun

附加参数，可选

测试模式运行，不执行实际的下载操作。

u

附加参数，可选

增量下载操作，设置该参数后，下载每个对象时会对比本地对应路径的文件，仅在文件不存在，或者文件大小与对象大小不一致，或者文件的最后修改时间早于对象的最后修改时间时进行下载。

vlength

附加参数，可选

下载完成后，验证本地文件大小是否与桶中对象的大小一致。

vmd5

附加参数，可选

下载完成后，验证本地文件的MD5值是否与桶中对象的MD5值一致。

说明：

桶中对象必须包含元数据x-obs-meta-md5chksum，否则会忽略MD5值校验。

注意：

如果您的业务涉及加密场景，请勿使用该参数。

p

附加参数，可选

每个分段下载任务的最大并发数，默认为配置文件中的defaultParallels。

threshold

附加参数，可选

开启分段下载任务的阈值，单位：字节，默认为配置文件中的defaultBigfileThreshold。

说明：
  • 如果待下载的对象小于该阈值，则使用直接下载模式；否则使用分段下载模式；
  • 直接下载模式不会产生断点记录文件，不支持断点续传；
  • 支持带容量单位配置，例如，配置1MB代表1048576字节。

ps

附加参数，可选

每个分段下载任务的段大小，单位：字节，默认为配置文件中的defaultPartSize。

说明：
  • 支持带容量单位配置，例如，配置1MB代表1048576字节；
  • 支持配置为auto，此时obsutil会根据源对象大小自动设置每个分段任务的段大小。

cpd

附加参数，可选

生成断点记录文件的文件夹，默认为运行obsutil命令的用户目录的子文件夹.obsutil_checkpoint。

说明：

每个分段下载任务会产生唯一对应的断点记录文件并保存至该文件夹的down子文件夹下，分段任务执行成功后，对应的断点记录文件会被自动删除；分段任务执行失败或被中断后，下次执行该分段任务时会尝试通过对应的断点记录文件恢复任务。

f

附加参数，批量下载时可选

强制操作，不进行询问提示。

j

附加参数，批量下载时可选

批量下载时的最大并发数，默认为配置文件中的defaultJobs。

说明：

工具会保证该值至少为1。

exclude

附加参数，批量下载时可选

不包含源对象的匹配模式，如：*.txt。

说明：
  • 支持“*”匹配多个任意字符和“?”匹配单个任意字符，例如abc*.txt代表匹配以abc开头以.txt结尾的任意文件；
  • 您可以使用“\*”代表匹配“*”字符本身，使用“\?”代表匹配“?”字符本身；
  • 如果待下载的对象名匹配该参数，则跳过该对象的复制；
须知：
  • 建议使用引号传递该匹配模式（macOS/Linux操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果；
  • 该匹配模式作用于对象全路径（含从根路径开始的对象前缀和对象名，例如，桶内对象路径为obs://bucket/src1/src2/test.txt，则对象的全路径为src1/src2/test.txt）；
  • 该匹配模式仅适用于对象名非“/”结尾的对象；
  • 支持指定多个exclude参数，如-exclude=*.xxx -exclude=*.xxx

include

附加参数，批量下载时可选

包含源对象的匹配模式，如：*.jpg。

说明：
  • 支持“*”匹配多个任意字符和“?”匹配单个任意字符；
  • 您可以使用“\*”代表匹配“*”字符本身，使用“\?”代表匹配“?”字符本身；
  • 首先执行exclude的匹配规则，如果待下载的对象名不匹配exclude，则判断待下载的对象名是否匹配该参数，如果匹配则下载该对象，否则跳过该文件的下载。
须知：
  • 建议使用引号传递该匹配模式（macOS/Linux操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。
  • 该匹配模式作用于对象全路径（含从根路径开始的对象前缀和对象名，例如，桶内对象路径为obs://bucket/src1/src2/test.txt，则对象的全路径为src1/src2/test.txt）。
  • 该匹配模式仅适用于对象名非“/”结尾的对象。
  • 支持指定多个include参数，如-include=*.xxx -include=*.xxx

timeRange

附加参数，批量下载时可选

下载对象时的时间段匹配模式，仅下载最后修改时间在该时间段内的对象。

该匹配模式优先级低于对象名匹配模式：exclude和include，优先执行对象名匹配模式后才会执行该匹配模式。

说明：
  • 使用“time1-time2”，代表匹配的时间段，其中time1必须小于等于time2，格式为yyyyMMddHHmmss。
  • 时间格式支持自动补全，例如yyyyMMdd等价于yyyyMMdd000000，yyyyMM等价于yyyyMM01000000。
  • 使用“*-time2”，代表匹配最后修改时间在time2之前的所有文件，使用“time1-*”，代表匹配最后修改时间time1之后的所有文件。
须知：
  • 该匹配模式表示的时间是UTC时间。
  • 该匹配模式仅适用于对象名非“/”结尾的对象。

mf

附加参数，可选

设置名称匹配模式（include、exclude）和时间匹配模式（timeRange）对对象名以“/”结尾的对象也生效。

o

附加参数，可选

生成结果清单文件的文件夹，命令执行完成后，会在该文件夹下生成结果清单文件（可能包含成功结果、失败结果和警告结果三个文件），默认为运行obsutil命令的用户目录的子文件夹.obsutil_output。

说明：
  • 结果清单文件命名规则：share-cp_{succeed | failed | warning}_report_时间_TaskId.txt。
  • 单个结果清单文件默认情况下最大为30MB且最大可保留的文件个数为1024，可在配置文件中通过recordMaxLogSize和recordBackups分别配置。
  • 当涉及多文件/文件夹时，如需确认失败任务的具体错误信息，可参考结果清单文件夹下的失败结果清单文件及日志路径下的日志文件；

config

附加参数，可选

运行当前命令时的自定义配置文件，可支持的配置参数请参考配置参数说明。

响应结果

请参考上传对象的响应结果。

父主题： 对象相关命令