Help Center/ Object Storage Service/ obsutil/ Object Commands/ Generating the Download Link of an Object
Updated on 2023-08-25 GMT+08:00

Generating the Download Link of an Object

Function

You can use this command to generate the download link of a specified object in a bucket or generate the download links of objects in a bucket in batches by object name prefix.

Command Line Structure

  • In Windows
    • Generating the download link of a single object
      obsutil sign obs://bucket/key [-e=300] [-config=xxx] [-endpoint=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • Generating the download links of objects in batches by object name prefix
      obsutil sign obs://bucket[/key] -r [-e=300] [-timeRange=time1-time2] [-include=*.xxx] [-exclude=*.xxx] [-o=xxx] [-config=xxx] [-endpoint=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • In Linux or macOS
    • Generating the download link of a single object
      ./obsutil sign obs://bucket/key [-e=300] [-config=xxx] [-endpoint=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • Generating the download links of objects in batches by object name prefix
      ./obsutil sign obs://bucket[/key] -r [-e=300] [-timeRange=time1-time2] [-include=*.xxx] [-exclude=*.xxx] [-o=xxx] [-config=xxx] [-endpoint=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

  • In Windows, run obsutil sign obs://bucket-test/test.txt to generate a single object download link:
    obsutil sign obs://bucket-test/test.txt
    
    Download url of [obs://bucket-test/test.txt] is:
      http://your-endpoint/bucket-test/test.txt?AccessKeyId=xxxx&Expires=1552548758&Signature=xxxx
  • In Windows, run obsutil sign obs://bucket-test/test/ -r to generate object download links in batches:
    obsutil sign obs://bucket-test/test/ -r
    
    Generate download urls for objects . 
    
    Generate the download url(s) for the objects in the bucket [bucket-test] finished 
    Task id: af4dc692-6a88-4541-8156-ff1a889d2288
    • If there are a large number of objects, obsutil saves the object download links to a specific file. The file name is associated with the task ID. For instance, the task ID in the example above is af4dc692-6a88-4541-8156-ff1a889d2288, so the file name should be sign_succeed_report_{timestamp}_af4dc692-6a88-4541-8156-ff1a889d2288.txt.
    • By default, the file is stored under folder .obsutil_output in your user directory. You can also use parameter -o to specify a new folder.

Parameter Description

Parameter

Optional or Mandatory

Description

bucket

Mandatory

Bucket name

key

Optional

Object name used for generating the download link of a single object, or object name prefix used for generating download links of objects in batches

e

Optional (additional parameter)

Validity period of the generated download links of objects, in seconds. Minimum value: 60s. Default value: 300s

r

Mandatory when generating download links of objects in batches (additional parameter)

Generates the download links of objects in batches by a specified object name prefix.

exclude

Optional when generating download links of objects in batches (additional parameter)

Indicates the matching patterns of objects that are excluded, for example: *.txt.

NOTE:
  • The asterisk (*) represents any group of characters, and the question mark (?) represents any single character. For instance, abc*.txt indicates any file whose name starts with abc and ends with .txt.
  • You can use \* to represent * and \? to represent ?.
  • If the name of the object to be downloaded matches the value of this parameter, the object is skipped.
NOTICE:
  • You are advised to use quotation marks for the matching pattern to prevent special characters from being escaped by the OS and leading to unexpected results. Use single quotation marks for Linux or macOS and quotation marks for Windows.
  • The matching pattern applies to the absolute path of an object, including the object name prefix and object name starting from the root directory. For example, if the path of an object in the bucket is obs://bucket/src1/src2/test.txt, then the absolute path of the object is src1/src2/test.txt.
  • This matching pattern applies only to objects whose names do not end with a slash (/).
  • Multiple exclude parameters can be specified, for example, -exclude=*.xxx -exclude=*.xxx.

include

Optional when generating download links of objects in batches (additional parameter)

Indicates the matching patterns of objects that are included, for example: *.jpg.

NOTE:
  • The asterisk (*) represents any group of characters, and the question mark (?) represents any single character.
  • You can use \* to represent * and \? to represent ?.
  • Only after identifying that the name of the file to be downloaded does not match the value of exclude, the system checks whether the file name matches the value of this parameter. If yes, the file is downloaded. If not, the file is skipped.
NOTICE:
  • You are advised to use quotation marks for the matching pattern to prevent special characters from being escaped by the OS and leading to unexpected results. Use single quotation marks for Linux or macOS and quotation marks for Windows.
  • The matching pattern applies to the absolute path of an object, including the object name prefix and object name starting from the root directory. For example, if the path of an object in the bucket is obs://bucket/src1/src2/test.txt, then the absolute path of the object is src1/src2/test.txt.
  • This matching pattern applies only to objects whose names do not end with a slash (/).
  • Multiple include parameters can be specified, for example, -include=*.xxx -include=*.xxx.

timeRange

Optional (additional parameter)

Indicates the time range matching pattern when generating download links of objects. Only the download links of objects whose latest modification time is within the configured time range are generated.

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:
  • Time in the matching pattern is the UTC time.
  • This matching pattern applies only to objects whose names do not end with a slash (/).
  • The matching time range is represented in time1-time2, where time1 must be earlier than or the same as time2. The time format is yyyyMMddHHmmss.
  • Automatic formatting is supported. For example, yyyyMMdd is equivalent to yyyyMMdd000000, and yyyyMM is equivalent to yyyyMM01000000.
  • If this parameter is set to *-time2, all files whose latest modification time is earlier than time2 are matched. If it is set to time1-*, all files whose latest modification time is later than time1 are matched.

o

Optional when generating download links of objects in batches (additional parameter)

Indicates the folder where operation result lists reside. After the command is executed, result lists (possibly including success and failure 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:
  • The naming rule for result lists is as follows: sign_{succeed | failed}_report_time_TaskId.txt

    By default, the maximum size of a single result list is 30 MB and the maximum number of result lists that can be retained is 1024. You can set the maximum size and number by configuring recordMaxLogSize and recordBackups in the configuration file.

config

Optional (additional parameter)

User-defined configuration file for executing a command. For details about parameters that can be configured, see Parameter Description.

endpoint

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.