Object Storage Service:Customize the filename for downloading an OSS file

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 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. If a pre-signed URL does not specify the Content-Disposition field, the value of this field is retrieved from the file's metadata.

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 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 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 previewing: You can allow users to preview or test a file without changing its original or default download name.

Permissions

To generate a signed URL for downloading an object, you must have the oss:GetObject permission. For more information, see Grant custom access policies 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 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 lets you 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 sample code in other languages, see Share files using file URLs.

Setting filenames for all downloaded files using file 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 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 Grant custom access policies 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 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 this code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

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

# Enter the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot include the bucket name.
object_name = 'exampledir/exampleobject.txt'

# The filename you want users to see when they download the file. This name must be URL-encoded.
download_filename = quote('desired-filename.txt')

# Update the file metadata to set the filename for download.
# Note: This update operation replaces all of the object's metadata.
# If you want to keep other existing metadata,
# you must first get the current metadata, modify it, and then update it with the complete set of metadata.
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.