OSS文件下載時文件名的顯示優(yōu)先級

文件下載時顯示的文件名由以下因素決定：

1. 預(yù)簽名URL的response-content-disposition參數(shù)： 使用預(yù)簽名URL并指定response-content-disposition參數(shù)時，該參數(shù)覆蓋文件元數(shù)據(jù)中的Content-Disposition設(shè)置。

2. 文件元數(shù)據(jù)中的Content-Disposition字段： 如果未通過預(yù)簽名URL指定，將檢查文件的元數(shù)據(jù)中的Content-Disposition字段。

3. OSS文件名： 如果上述兩者都未設(shè)置，將默認使用對象鍵名的文件名部分。

通過預(yù)簽名URL設(shè)置單次下載的文件名

預(yù)簽名URL是OSS提供的一種臨時授權(quán)訪問鏈接，可以讓用戶在一定時間內(nèi)下載私有權(quán)限的文件。通過在生成預(yù)簽名URL的過程中添加response-content-disposition參數(shù)，您可以控制用戶在本次下載文件時看到的文件名，而不需要修改文件元數(shù)據(jù)中的Content-Disposition字段或OSS文件名。

使用場景

• 臨時文件共享：當(dāng)您想要與特定用戶分享一個文件，并且希望該用戶在下載時看到一個特定的文件名，而不是存儲在OSS上的原始文件名。

• 個性化下載：如果您要為不同的用戶提供個性化的文件名，例如根據(jù)用戶的姓名或訂單號生成的文件名，可以使用預(yù)簽名URL的方式來實現(xiàn)。

• 測試和預(yù)覽：如果您想要提供一份文件供用戶預(yù)覽或測試，但并不想改變該文件的原始或默認下載名稱。

權(quán)限說明

要生成用于下載文件的預(yù)簽名URL，您必須具有oss:GetObject權(quán)限。具體操作，請參見為RAM用戶授權(quán)自定義的權(quán)限策略。

注意事項

• response-content-disposition參數(shù)是在生成預(yù)簽名URL時指定的，只對該URL有效。

• 確保在指定文件名時使用URL編碼，避免特殊字符造成的問題。

• 預(yù)簽名URL有有效期，過期后無法使用，確保提供給用戶的URL在他們下載文件之前是有效的。

• 如果OSS中的文件已經(jīng)設(shè)置了Content-Disposition，使用預(yù)簽名URL內(nèi)的response-content-disposition將臨時覆蓋它。

示例代碼

生成預(yù)簽名URL的過程中添加response-content-disposition參數(shù)的Python示例代碼如下：

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

# 從環(huán)境變量中獲取訪問憑證。運行本代碼示例之前，請確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# yourEndpoint填寫B(tài)ucket所在地域?qū)?yīng)的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
# 填寫B(tài)ucket名稱。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
object_name = 'exampledir/exampleobject.txt'

# 用戶下載時希望看到的文件名，這里需要進行URL編碼。
download_filename = quote('desired-filename.txt')

# 設(shè)置響應(yīng)頭中的Content-Disposition，指定下載時使用的文件名。
params = {'response-content-disposition': f'attachment; filename="{download_filename}"'}

# 生成下載文件的簽名URL，有效時間為3600秒。
# 設(shè)置slash_safe為True，OSS不會對Object完整路徑中的正斜線（/）進行轉(zhuǎn)義，此時生成的簽名URL可以直接使用。
url = bucket.sign_url('GET', object_name, 3600, params=params, slash_safe=True)

print('簽名URL的地址為：', url)

更多語言的示例代碼，請參見使用文件URL分享文件。

通過文件元數(shù)據(jù)設(shè)置所有下載的文件名

在OSS中，Content-Disposition頭部用于指定對象被下載時的默認文件名。當(dāng)您希望某個文件的所有下載請求都使用新的文件名時，您可以更新文件的元數(shù)據(jù)中的Content-Disposition字段，而不需要修改文件在OSS上的實際文件名。一旦修改了Content-Disposition，所有未指定response-content-disposition參數(shù)的下載請求都將看到新設(shè)置的文件名。

使用場景

• 長期文件共享：當(dāng)文件需要被多次下載，并且每次下載都希望顯示相同文件名時，通過修改文件元數(shù)據(jù)可以實現(xiàn)這一目標(biāo)。

• 文檔庫或資源中心：在企業(yè)的文檔庫或公共資源中心中，您可能希望所有文件都具有固定的、描述性的文件名，方便識別和歸檔。

• 持續(xù)性產(chǎn)品更新：如果您定期更新產(chǎn)品文檔或軟件，希望用戶始終通過同一個鏈接下載最新版本，且文件名保持不變，可以通過設(shè)置元數(shù)據(jù)來實現(xiàn)。

權(quán)限說明

要修改文件元數(shù)據(jù)，您必須具有oss:PutObject權(quán)限。具體操作，請參見為RAM用戶授權(quán)自定義的權(quán)限策略。

注意事項

• 確保在設(shè)置Content-Disposition時考慮文件名中可能的特殊字符，并進行適當(dāng)?shù)?span id="z68uejxpaoma" class="help-letter-space">URL編碼。

• 更新Content-Disposition是通過PUT操作覆蓋現(xiàn)有對象的元數(shù)據(jù)來實現(xiàn)的。如果您希望保留除Content-Disposition以外的其他元數(shù)據(jù)，您需要首先獲取對象的當(dāng)前元數(shù)據(jù)，對其進行必要的修改，然后使用更新后的元數(shù)據(jù)集合一起執(zhí)行PUT操作。

• 為了避免重新上傳整個對象內(nèi)容并減少數(shù)據(jù)覆蓋的風(fēng)險，推薦使用SDK中的update_object_meta接口而非PutObject接口來安全地更新對象的元數(shù)據(jù)。

示例代碼

更新文件的元數(shù)據(jù)中的Content-Disposition字段的Python示例代碼如下：

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

# 從環(huán)境變量中獲取訪問憑證。運行本代碼示例之前，請確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# yourEndpoint填寫B(tài)ucket所在地域?qū)?yīng)的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
# 填寫B(tài)ucket名稱。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
object_name = 'exampledir/exampleobject.txt'

# 用戶下載時希望看到的文件名，這里需要進行URL編碼。
download_filename = quote('desired-filename.txt')

# 更新文件元數(shù)據(jù)，設(shè)置下載時的文件名。
# 注意：此更新操作會替換掉對象的所有元數(shù)據(jù)。
# 如果您想保留其他已有的元數(shù)據(jù)，需要先獲取現(xiàn)有的元數(shù)據(jù)，
# 然后進行修改，并將完整的元數(shù)據(jù)集合一起更新。
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

更多語言的示例代碼，請參見管理文件元數(shù)據(jù)。