Sharing an Object

Scenarios

You can share temporary URLs of your objects with others for them to access your objects stored in OBS.

Background Information

You can share files with other users temporarily or permanently.

Temporary sharing:
Share a file to other users through the temporary URL of the file. File sharing is temporary. All sharing URLs are only valid for a limited period of time.

A temporary URL consists of the access domain name and the temporary authentication information of a file. Example:
```
https://bucketname.obs.ap-southeast-1.myhuaweicloud.com:443/image.png?AccessKeyId=xxx&Expires=xxx&x-obs-security-token=xxx&Signature=xxx
```
The temporary authentication information contains the AccessKeyId, Expires, x-obs-security-token, and Signature parameters. AccessKeyId, x-obs-security-token, and Signature are used for authentication. The Expires parameter specifies the validity period of the authentication.

For details about the temporary authentication method and parameters, see Authentication of Signature in a URL in the Object Storage Service API Reference.
Permanent sharing:
If you set the permission for an object to allow anonymous users to read it, anonymous users can access the object through the URL that you shared. For details about how to configure permissions, see Granting Public Read Permissions on Objects to Anonymous Users.

The method of using a browser to access objects varies depending on the object type. You can directly open .txt and .html files using a browser. However, when you open .exe and .dat files using a browser, the files are automatically downloaded to your local computer.

For details about how to obtain the object access URL, see How Do I Obtain the Access Path to an Object?

If access to an object using the URL fails, fix the problem by referring to Why Can't I Access an Object Through Its URL?

Limitations and Constraints

An authorization code is not required for temporarily sharing a file. Temporarily sharing a folder requires an authorization code when the method of sharing by access code is used. For details, see Sharing a Folder.

The following table describes the URL validity period of the files that are temporarily shared in different ways.

Way	URL Validity Period
OBS Console	The URL is valid for 1 minute to 18 hours. After an object is shared, the system will generate a URL that contains the temporary authentication information, valid for five minutes since its generation by default. Each time you change the validity period of a URL, OBS obtains the authentication information again to generate a new URL for sharing. The new URL becomes valid at the moment the validity period is changed. If you need a longer validity period, use OBS Browser+ that allows a validity period of up to one year to share the object. If you want a shared object to be permanently valid, use a bucket policy to grant anonymous users the read-only permission for the object.
SDKs	Configure parameter Expires to specify when a temporary authorization expires. The temporary authorization expires in 20 years in maximum.
API	Configure parameter Expires to specify when a temporary authorization expires. The temporary authorization expires in 20 years in maximum.
OBS Browser+	When you log in to OBS Browser+ using an account and password, a shared URL can be valid for 24 hours at most. The default validity period is 10 hours. If a longer validity period is required, use the permanent AK/SK for login.
obsutil	Use the additional parameter e to specify when an object download URL expires. The minimum value is 60s and the default one is 300s. There is no upper limit on the expiration time.

Only buckets of version 3.0 support object sharing. For details about how to query the bucket version, see Checking OBS Version (OBS 2.0 or OBS 3.0).
Archive objects can be shared only after they have been restored.
Deep Archive objects can be shared only after they have been restored.
Object sharing is available in all regions except CN Southwest-Guiyang1.

Ways to Share an Object

You can use OBS Console, APIs, SDKs, OBS Browser+, or obsutil to share an object.

Using OBS Console

In the navigation pane of OBS Console, choose Object Storage.
In the bucket list, click the bucket you want to operate. The Objects page is displayed.
Locate the file to be shared and click Share in the Operation column.

Once the Share File dialog box is opened, the URL is effective and valid for five minutes by default. If you change the validity period, the authentication information in the URL changes accordingly, and the URL's new validity period starts upon the change.

Figure 1 Sharing a file
Operate the URL as follows:
- Click Open URL to preview the file on a new page or directly download it to your default download path.
- Click Copy Link to share the link to others for them to access this file using a browser.
- Click Copy Path to share the file path to users who have access to the bucket. The users then can search for the file by pasting the shared path to the search box of the bucket.
Within the URL validity period, anyone who has the URL can access the file.

Using the API

Authentication of Signature in a URL

Using SDKs

Using the GUI Tool - OBS Browser+

Log in to OBS Browser+.
Locate the object you want to share and click next to the object. The window shown in Figure 2 or Figure 3 is displayed.

Figure 2 Sharing a file

Figure 3 Sharing a folder
Click Copy Link to copy the object link to a browser and open it. Then you can access the object.

To allow anonymous users to access Archive objects using URLs, ensure that these objects are in the Restored state.

Using the CLI Tool - obsutil

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 the current command. To learn the parameters that can be configured in this file, see Configuration Parameters.
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.