すべてのプロダクト
Search

このプロダクト

    Object Storage Service:OSS ファイルのダウンロード時におけるファイル名のカスタマイズ

    ドキュメントセンター

    Object Storage Service:OSS ファイルのダウンロード時におけるファイル名のカスタマイズ

    最終更新日:Mar 21, 2026

    OSS のオブジェクトキーは不変であり、しばしば記述的でない名称になっています。たとえば、UUID のような a3f2c1d0-... などが該当します。ユーザーがオブジェクトをダウンロードした際に表示されるファイル名を制御するには、以下の 2 つの方法のいずれかを使用します。

    • 署名付き URL に `response-content-disposition` を含める方法 — オブジェクトのメタデータを変更せずに、その特定のダウンロードのみに適用されるファイル名をオーバーライドします。

    • `Content-Disposition` メタデータヘッダー — オブジェクトのすべてのダウンロードに適用されるデフォルトのファイル名を設定します。

    ダウンロード時のファイル名の決定順序

    OSS では、ダウンロード時に表示されるファイル名を以下の優先度順に決定します。

    優先度ソース適用条件
    1（最高）response-content-disposition パラメーター（署名付き URL 内）署名付き URL に該当パラメーターが含まれている場合
    2Content-Disposition オブジェクトメタデータヘッダー署名付き URL に該当パラメーターが含まれていない場合
    3（フォールバック）OSS オブジェクトキー上記のいずれも設定されていない場合

    署名付き URL を使用して特定のダウンロード向けにファイル名を設定する

    署名付き URL は、非公開オブジェクトへの一定期間限定のアクセスを許可します。ダウンロード時に表示されるファイル名を指定するには、URL に response-content-disposition パラメーターを追加します。この方法ではオブジェクトのメタデータは変更されないため、他のダウンロード方法には影響しません。

    主な利用シーン：

    • オブジェクトの共有：内部のオブジェクトキーを外部に露出させることなく、意味のあるファイル名を受信者に表示できます。

    • パーソナライズされたダウンロード：ユーザーごとに異なる署名付き URL を生成し、ユーザー名や注文番号などに基づいたカスタムファイル名を付与できます。

    • プレビューおよびテスト：デフォルトのファイル名を変更することなく、レビュー担当者がテスト用に分かりやすいファイル名でダウンロードできるようにできます。

    前提条件

    開始する前に、以下の条件を満たしていることを確認してください。

    注意事項

    • response-content-disposition は、署名付き URL のみに適用されます。同一オブジェクトの他のダウンロード方法には影響しません。

    • 特殊文字によるエラーを防ぐため、オブジェクト名は URL エンコードしてください。

    • 署名付き URL は有効期間が過ぎると有効期限切れになります。ユーザーとの URL 共有に際しては、有効期限を考慮してください。

    • オブジェクトに Content-Disposition メタデータヘッダーが既に設定されている場合、署名付き URL のパラメーターが優先され、メタデータヘッダーは無視されます。

    サンプルコード

    以下の Python コード例では、オブジェクトを desired-filename.txt というファイル名でダウンロードさせる署名付き URL を生成します。

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

# 環境変数から認証情報を読み込みます。
# このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET を設定してください。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# <bucket_name> をバケット名に置き換えます。
# エンドポイントをバケットのリージョンに対応するエンドポイントに置き換えます。
# 例: 中国 (杭州) リージョンの場合は https://oss-cn-hangzhou.aliyuncs.com。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# バケット内のオブジェクトの完全パス。バケット名は含めないでください。
object_name = 'exampledir/exampleobject.txt'

# オブジェクトをダウンロードする際にユーザーに表示されるファイル名。
# 特殊文字を処理するために名前を URL エンコードします。
download_filename = quote('desired-filename.txt')

# このオブジェクトの今後のすべてのダウンロードに対してユーザーに表示されるファイル名を設定します。
#
# 注: update_object_meta は既存のすべてのメタデータヘッダーを上書きします。
# 他のヘッダーを保持するには、最初に bucket.get_object_meta() を使用して取得し、
# 変更内容をマージしてから、完全なセットで update_object_meta を呼び出します。
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

    他の言語の例については、「オブジェクト URL を使用したオブジェクトの共有」をご参照ください。

    オブジェクトのメタデータを更新してすべてのダウンロード向けにファイル名を設定する

    Content-Disposition メタデータヘッダーを設定すると、オブジェクトのすべてのダウンロードに対してデフォルトのファイル名が適用されます。これは、response-content-disposition パラメーターを含まないすべてのリクエストに適用されます。

    主な利用シーン：

    • 長期的な共有：オブジェクトが繰り返しダウンロードされ、常に同じファイル名で表示される必要があります。

    • ドキュメントおよびリソースライブラリ：パブリックライブラリ内のファイルは、識別およびアーカイブが容易になるよう、一貫性があり、記述的な名称を持つ必要があります。

    • バージョン管理されたコンテンツ：オブジェクトをインプレースで更新（キーは同一、内容のみ更新）し、すべてのダウンロードで安定した人間が読み取り可能なファイル名を維持できます。

    前提条件

    開始する前に、以下の条件を満たしていることを確認してください。

    注意事項

    • Content-Disposition の値に含まれるファイル名は、特殊文字を処理するため URL エンコードしてください。

    • このヘッダーの更新は、すべてのオブジェクトメタデータを上書きします。他の既存のヘッダーを保持するには、まず現在のメタデータを取得し、Content-Disposition を更新したうえで、完全な更新済みセットを書き戻してください。

    • update_object_meta を使用して、オブジェクトを再アップロードせずにメタデータを更新します。これにより、誤ったデータの上書きを回避できます。 PutObject の代わりにこの方法を使用してください。

    サンプルコード

    以下の Python コード例では、Content-Disposition ヘッダーを設定し、オブジェクトを desired-filename.txt というファイル名でダウンロードできるようにします。

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

# 環境変数から認証情報を読み込みます。
# このコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET を設定してください。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# <bucket_name> を実際のバケット名に置き換えます。
# エンドポイントは、バケットのリージョンに対応するものに置き換えてください。
# 例：中国 (杭州) リージョンの場合、https://oss-cn-hangzhou.aliyuncs.com
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# バケット内のオブジェクトのフルパス。バケット名は含めません。
object_name = 'exampledir/exampleobject.txt'

# ユーザーがダウンロード時に表示されるファイル名。
# 特殊文字を処理するため、URL エンコードします。
download_filename = quote('desired-filename.txt')

# このオブジェクトの今後のすべてのダウンロードでユーザーに表示されるファイル名を設定します。
#
# 注意：update_object_meta は、既存のすべてのメタデータヘッダーを上書きします。
# 他のヘッダーを保持するには、まず bucket.get_object_meta() で現在のメタデータを取得し、
# 変更をマージしたうえで、update_object_meta に完全な更新済みセットを渡してください。
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

    その他のプログラミング言語での例については、「オブジェクトメタデータの管理」をご参照ください。

    次のステップ