Object Storage Service:Specify names for downloaded objects

Naming rules for downloaded objects

The name of a downloaded object is determined based on the following rules:

1. Parameter response-content-disposition If an object is downloaded by using a signed URL that contains the response-content-disposition parameter, the downloaded object has the name specified by the parameter, regardless of the value of the Content-Disposition metadata header.

2. Metadata header Content-Disposition If the response-content-disposition parameter is not specified in the signed URL, OSS uses the value of the Content-Disposition metadata header as the name of the downloaded object.

3. OSS object key If response-content-disposition and Content-Disposition are not specified, the downloaded object has the same name as the object key in OSS.

Specify a name for specific downloads of an object by using a signed URL

A signed URL grants a user time-limited access to a private object in OSS. You can add the response-content-disposition parameter to a signed URL of an object to specify a different name for the object when it is downloaded by using the URL, without the need to modify the Content-Disposition metadata header of the object.

Scenarios

• Object sharing: You can use a signed URL to share an object with another user and specify a name that is displayed when the user downloads the object. This way, your original object key is not exposed.

• Personalized downloads: You can use signed URLs to present personalized names of downloaded objects to different users. For example, you can customize names of downloaded objects by username or order number.

• Testing and preview: You can use a signed URL to share an object for testing or preview without changing the original or default object download name.

Permissions

To generate a signed URL for object downloading, you must have the oss:GetObject permission. For more information, see Attach a custom policy to a RAM user.

Usage notes

• You can specify the response-content-disposition parameter when you create a signed URL. The parameter applies to only the signed URL.

• Make sure that you specify URL-encoded object names to avoid errors caused by special characters.

• A signed URL has a validity period and cannot be used after it expires. Consider the URL validity period when you provide users with a signed URL.

• If the Content-Disposition metadata header is specified for an object and the object is downloaded by using a signed URL that contains the response-content-disposition parameter, the Content-Disposition metadata header is ignored and the value of the response-content-disposition parameter is used as the name of the downloaded object.

Sample code

The following sample code in Python provides an example on how to specify the response-content-disposition parameter when you create a signed URL:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from urllib.parse import quote

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
object_name = 'exampledir/exampleobject.txt'

# Create an object name that you want to display when the object is downloaded. You need to URL-encode the name. 
download_filename = quote('desired-filename.txt')

# Specify the name of the downloaded object. This name is the value of the Content-Disposition header in the response to the download request. 
params = {'response-content-disposition': f'attachment; filename="{download_filename}"'}

# Set the validity period of the signed URL to 3,600 seconds. 
# Set the slash_safe parameter to True to prevent OSS from identifying the forward slashes (/) in the full path of the object as escape characters. This allows you to use the generated signed URL to download the object. 
url = bucket.sign_url('GET', object_name, 3600, params=params, slash_safe=True)

print ('Signed URL:', url)

For code examples in other programming languages, see Share objects with object URLs.

Specify a name for all downloads of an object by configuring object metadata

The Content-Disposition metadata header specifies the default name for an object when it is downloaded. If you want an object to have a new name for all requests to download the object, you can set the Content-Disposition metadata header to the new name. The new name specified by the Content-Disposition header applies to all download requests that do not contain the response-content-disposition parameter.

Scenarios

• Long-term data sharing: If an object is expected to be downloaded multiple times with the same object name each time, you can modify the metadata header to achieve this goal.

• Archiving: In scenarios of public document libraries or resource centers, you may need all documents or resources to have fixed and descriptive names for easy identification and archiving.

• Regular updates: If you want users to download the latest version of regularly updated documentation or software by using the same URL and with a consistent name, you can set the metadata header of documentation or software in OSS.

Permissions

To modify object metadata, you must have the oss:PutObject permission. For more information, see Attach a custom policy to a RAM user.

Usage notes

• Consider special characters that may be included in object names when you set the Content-Disposition header. We recommend that you use URL encoding.

• A change to the Content-Disposition header is implemented by using the PUT method to overwrite the existing object metadata. If you only update the Content-Disposition header of an object and keep all the other metadata headers unchanged, you need to query existing metadata of the object, update the header, and use the updated metadata collection to initiate a PUT request.

• To avoid re-uploading the object and reduce the risk of overwriting existing data, we recommend that you use update_object_meta instead of PutObject to update object metadata.

Sample code

The following sample code in Python provides an example on how to modify the value of the Content-Disposition header:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from urllib.parse import quote

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
object_name = 'exampledir/exampleobject.txt'

# Create an object name that you want to display when the object is downloaded. You need to URL-encode the name. 
download_filename = quote('desired-filename.txt')

# Update metadata to specify a name for the downloaded object. 
# Note: This update operation overwrites all metadata headers of the object. 
# If you want to retain values for all the other existing metadata headers, you need to obtain the existing metadata headers first. 
# Then, modify the desired header and use the modified metadata collection to update the metadata of the object. 
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

For code examples in other programming languages, see Manage object metadata.