Downloading an Object
Function
You can use this command to download an object or download objects in batches by object name prefix to your local PC.
- Do not change the source objects in the OBS bucket when downloading a single object or objects in batches. Otherwise, the download may fail or data may be inconsistent.
- If the object to be downloaded is in the Infrequent Access storage class, you must restore it before downloading it. Otherwise, the download will fail.
Command Line Structure
- In Windows
- Downloading a single object
obsutil cp obs://bucket/key file_or_folder_url [-tempFileDir=xxx] [-dryRun] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-versionId=xxx] [-encoding-type=url] [-ps=auto] [-cpd=xxx][-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Downloading objects in batches
obsutil cp obs://bucket[/key] folder_url -r [-tempFileDir=xxx] [-dryRun] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-encoding-type=url] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Downloading a single object
- In Linux or macOS
- Downloading a single object
./obsutil cp obs://bucket/key file_or_folder_url [-tempFileDir=xxx] [-dryRun] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-versionId=xxx] [-encoding-type=url] [-ps=auto] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Downloading objects in batches
./obsutil cp obs://bucket[/key] folder_url -r [-tempFileDir=xxx] [-dryRun] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Downloading a single object
Examples
- Take the Windows OS as an example. Run the obsutil cp obs://bucket-test/key d:\temp\test.txt command to download a single object.
obsutil cp obs://bucket-test/key d:\temp\test.txt Parallel: 3 Jobs: 3 Threshold: 524288000 PartSize: 5242880 Exclude: Include: VerifyLength: false VerifyMd5: false CheckpointDir: xxxx [==========================================] 100.00% 4.86 KB/s 8.46MB/8.46MB 0s Download successfully, 8.46MB, obs://bucket-test/key --> d:\temp\test.txt
- Take the Windows OS as an example. Run the obsutil cp obs://bucket-test/temp d:\ -f -r command to download objects in batches.
obsutil cp obs://bucket-test/temp d:\ -f -r Parallel: 3 Jobs: 3 Threshold: 524288000 PartSize: 5242880 Exclude: Include: VerifyLength: false VerifyMd5: false CheckpointDir: xxxx Task id: 3066a4b0-4d21-4929-bb84-4829c32cbd0f OutputDir: xxxx [======================================================] 100.00% tps:17.86 155.59 KB/s 7.20MB/7.20MB 0s Succeed count is: 6 Failed count is: 0 Metrics [max cost:153 ms, min cost:129 ms, average cost:92.00 ms, average tps:17.86] Task id: 3066a4b0-4d21-4929-bb84-4829c32cbd0f
- For more examples, see Download.
Parameter Description
Parameter |
Optional or Mandatory |
Description |
---|---|---|
file_or_folder_url |
Mandatory for downloading an object |
Local file/folder path |
folder_url |
Mandatory for downloading objects in batches |
Local folder path |
bucket |
Mandatory |
Bucket name |
key |
Mandatory for downloading an object Optional for downloading objects in a batch |
Indicates the name of the object to be downloaded, or the name prefix of the objects to be downloaded in batches. This parameter cannot be left blank when downloading an object. The saving and naming rules are as follows:
During batch download, the saving rules are as follows:
NOTE:
|
fr |
Optional for downloading an object (additional parameter) |
Generates an operation result list when downloading an object. |
flat |
Optional for downloading objects in batches (additional parameter) |
The name prefix of the parent object is excluded when downloading objects in batches. |
tempFileDir |
Optional (additional parameter) |
Indicates the directory for storing temporary files during multipart download. The default value is the value of defaultTempFileDir in the configuration file.
NOTE:
|
dryRun |
Optional (additional parameter) |
Conducts a dry run. |
u |
Optional (additional parameter) |
Indicates incremental download. If this parameter is set, each object can be downloaded only when it does not exist in the local path, its size is different from the namesake one in the local path, or it has the latest modification time. |
vlength |
Optional (additional parameter) |
Checks whether the sizes of the local files are the same as those of the objects in the bucket after the download is complete. |
vmd5 |
Optional (additional parameter) |
Checks whether MD5 values of the local files are the same as those of the objects in the bucket after the download is complete.
NOTE:
Objects in the bucket must contain metadata x-obs-meta-md5chksum, or MD5 verification will be skipped. |
p |
Optional (additional parameter) |
Indicates the maximum number of concurrent multipart download tasks when downloading an object. The default value is the value of defaultParallels in the configuration file. |
threshold |
Optional (additional parameter) |
Indicates the threshold for enabling multipart download, in bytes. The default value is the value of defaultBigfileThreshold in the configuration file.
NOTE:
|
versionId |
Optional for downloading an object (additional parameter) |
Source object version ID that can be specified when downloading an object |
ps |
Optional (additional parameter) |
Indicates the size of each part in a multipart download task, in bytes. The default value is the value of defaultPartSize in the configuration file.
NOTE:
|
fs |
Optional (additional parameter) |
Specifies whether the method of listing parallel file systems is applied. If you are listing parallel file systems, you are recommended to add this parameter.
CAUTION:
|
cpd |
Optional (additional parameter) |
Indicates the folder where the part records reside. The default value is .obsutil_checkpoint, the subfolder in the home directory of the user who executes obsutil commands.
NOTE:
A part record is generated during a multipart download and saved to the down subfolder. After the download succeeds, its part record is deleted automatically. If the download fails or is suspended, the system attempts to resume the task according to its part record when you perform the download the next time. |
r |
Mandatory for downloading objects in batches (additional parameter) |
Copies objects in batches based on a specified object name prefix. |
f |
Optional for downloading objects in batches (additional parameter) |
Runs in force mode. |
j |
Optional for downloading objects in batches (additional parameter) |
Indicates the maximum number of concurrent tasks for downloading objects in a batch. The default value is the value of defaultJobs in the configuration file.
NOTE:
The value is ensured to be greater than or equal to 1. |
encoding-type |
Optional (additional parameter) |
If the object name contains special characters, set this parameter to url.
NOTE:
This parameter is only available for obsutil 5.5.12 and later. |
exclude |
Optional for downloading objects in batches (additional parameter) |
Indicates the matching patterns of source objects that are excluded, for example, *.txt.
NOTE:
NOTICE:
|
include |
Optional for downloading objects in batches (additional parameter) |
Specifies what formats of objects can be downloaded. If this parameter is set to *.jpg, only objects in the .jpg format can be downloaded.
NOTE:
NOTICE:
|
timeRange |
Optional for downloading objects in batches (additional parameter) |
Indicates the time range matching pattern when downloading objects. Only objects whose latest modification time is within the configured time range are downloaded. This pattern has a lower priority than the object matching patterns (exclude/include). That is, the time range matching pattern is executed after the configured object matching patterns.
NOTE:
NOTICE:
|
mf |
Optional (additional parameter) |
Indicates that the name matching pattern (include or exclude) and the time matching pattern (timeRange) also take effect on objects whose names end with a slash (/). |
o |
Optional (additional parameter) |
Indicates the folder where operation result lists reside. After the command is executed, result lists (possibly including success, failure, and warning files) are generated in the folder. The default value is .obsutil_output, the subfolder in the home directory of the user who executes obsutil commands.
NOTE:
|
config |
Optional (additional parameter) |
User-defined configuration file for executing a command. For details about parameters that can be configured, see Configuration Parameters. |
e |
Optional (additional parameter) |
Specifies the endpoint. |
i |
Optional (additional parameter) |
Specifies the user's AK. |
k |
Optional (additional parameter) |
Specifies the user's SK. |
t |
Optional (additional parameter) |
Specifies the user's security token. |
encoding-type |
Optional (additional parameter) |
If the object name contains special characters, set this parameter to url.
NOTE:
This parameter is only supported by obsutil 5.5.12 and later. |
Response
Refer to Response for uploading an object.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot