Menyesuaikan nama file untuk mengunduh file OSS - Object Storage Service

Kunci objek OSS bersifat immutable dan seringkali tidak deskriptif—misalnya, UUID seperti a3f2c1d0-.... Untuk mengontrol nama file yang muncul saat pengguna mengunduh objek, gunakan salah satu dari dua pendekatan berikut:

Signed URL dengan parameter `response-content-disposition` — mengganti nama file hanya untuk unduhan tersebut tanpa mengubah metadata objek.
Header metadata `Content-Disposition` — menetapkan nama file default yang berlaku untuk semua unduhan objek tersebut.

Cara menentukan nama file unduhan

OSS menentukan nama file yang diunduh berdasarkan urutan prioritas berikut:

Prioritas	Sumber	Berlaku saat
1 (tertinggi)	`response-content-disposition` dalam signed URL	Signed URL berisi parameter tersebut
2	`Content-Disposition` sebagai header metadata objek	Signed URL tidak berisi parameter tersebut
3 (fallback)	Kunci objek OSS	Tidak ada dari dua opsi di atas yang ditetapkan

Tetapkan nama file untuk unduhan tertentu menggunakan signed URL

Signed URL memberikan akses terbatas waktu ke objek privat. Tambahkan parameter response-content-disposition ke URL untuk menentukan nama file unduhan—metadata objek tidak diubah, sehingga metode unduhan lain tidak terpengaruh.

Kasus penggunaan umum:

Berbagi objek: Bagikan objek tanpa mengekspos kunci objek internalnya. Penerima melihat nama file yang bermakna.
Unduhan personalisasi: Hasilkan Signed URL per pengguna dengan nama file kustom (misalnya, berdasarkan username atau nomor pesanan).
Pratinjau dan pengujian: Izinkan penguji mengunduh objek dengan nama yang mudah digunakan untuk pengujian tanpa mengubah nama default.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Bucket OSS yang berisi objek target
Izin oss:GetObject. Untuk detailnya, lihat Attach a custom policy to a RAM user

Catatan penggunaan

Parameter response-content-disposition hanya berlaku untuk Signed URL tersebut—tidak memengaruhi unduhan lain dari objek yang sama.
Encode nama file dalam format URL untuk mencegah error akibat karakter khusus.
Signed URL kedaluwarsa setelah periode validitasnya berakhir. Pertimbangkan waktu kedaluwarsa saat membagikan URL kepada pengguna.
Jika objek juga memiliki header metadata Content-Disposition, parameter dalam Signed URL akan didahulukan dan header metadata tersebut diabaikan.

Contoh kode

Contoh Python berikut menghasilkan Signed URL yang menyebabkan objek diunduh dengan nama file desired-filename.txt.

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

# Muat kredensial dari variabel lingkungan.
# Atur OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET sebelum menjalankan kode ini.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Ganti <bucket_name> dengan nama bucket Anda.
# Ganti titik akhir dengan titik akhir untuk wilayah bucket Anda.
# Contoh: https://oss-cn-hangzhou.aliyuncs.com untuk wilayah Tiongkok (Hangzhou).
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Jalur lengkap objek dalam bucket. Jangan sertakan nama bucket.
object_name = 'exampledir/exampleobject.txt'

# Nama file yang ditampilkan kepada pengguna saat mereka mengunduh objek.
# URL-encode nama tersebut untuk menangani karakter khusus.
download_filename = quote('desired-filename.txt')

# Atur nama file yang ditampilkan kepada pengguna untuk semua unduhan mendatang objek ini.
#
# Catatan: update_object_meta menimpa SEMUA header metadata yang ada.
# Untuk mempertahankan header lainnya tetap utuh, ambil terlebih dahulu dengan bucket.get_object_meta(),
# gabungkan perubahan Anda, lalu panggil update_object_meta dengan set lengkap.
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

Untuk contoh dalam bahasa lain, lihat Membagikan objek dengan URL objek.

Tetapkan nama file untuk semua unduhan dengan memperbarui metadata objek

Header metadata Content-Disposition menetapkan nama file default untuk setiap unduhan objek. Ini berlaku untuk semua permintaan yang tidak menyertakan parameter response-content-disposition.

Kasus penggunaan umum:

Berbagi jangka panjang: Objek diunduh berulang kali dan harus selalu muncul dengan nama file yang sama.
Pustaka dokumen dan sumber daya: File dalam pustaka publik memiliki nama yang konsisten dan deskriptif untuk memudahkan identifikasi dan pengarsipan.
Konten versi: Perbarui objek secara langsung (kunci sama, konten baru) dan pertahankan nama file yang stabil serta mudah dibaca manusia untuk semua unduhan.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Bucket OSS yang berisi objek target
Izin oss:PutObject. Untuk detailnya, lihat Attach a custom policy to a RAM user

Catatan penggunaan

Encode nama file dalam nilai Content-Disposition dalam format URL untuk menangani karakter khusus.
Memperbarui header ini akan menimpa seluruh metadata objek. Untuk mempertahankan header lain yang sudah ada, ambil metadata saat ini terlebih dahulu, perbarui Content-Disposition, lalu tulis kembali seluruh set metadata yang telah diperbarui.
Gunakan update_object_meta alih-alih PutObject untuk memperbarui metadata tanpa mengunggah ulang objek, sehingga menghindari penimpaan data yang tidak disengaja.

Contoh kode

Contoh Python berikut menetapkan header Content-Disposition sehingga objek diunduh dengan nama file desired-filename.txt.

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

# Muat kredensial dari variabel lingkungan.
# Tetapkan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET sebelum menjalankan kode ini.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Ganti <bucket_name> dengan nama bucket Anda.
# Ganti endpoint dengan endpoint wilayah bucket Anda.
# Contoh: https://oss-cn-hangzhou.aliyuncs.com untuk wilayah China (Hangzhou).
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', '<bucket_name>')

# Jalur lengkap objek dalam bucket. Jangan sertakan nama bucket.
object_name = 'exampledir/exampleobject.txt'

# Nama file yang ditampilkan kepada pengguna saat mereka mengunduh objek.
# Encode nama dalam format URL untuk menangani karakter khusus.
download_filename = quote('desired-filename.txt')

# Tetapkan nama file yang ditampilkan kepada pengguna untuk semua unduhan mendatang objek ini.
#
# Catatan: update_object_meta menimpa SEMUA header metadata yang ada.
# Untuk mempertahankan header lain, ambil terlebih dahulu dengan bucket.get_object_meta(),
# gabungkan perubahan Anda, lalu panggil update_object_meta dengan set lengkap tersebut.
headers = {'Content-Disposition': f'attachment; filename="{download_filename}"'}
bucket.update_object_meta(object_name, headers)

Untuk contoh dalam bahasa lain, lihat Mengelola metadata objek.

Langkah selanjutnya

Share objects with object URLs — hasilkan dan bagikan Signed URL
Manage object metadata — perbarui header metadata lainnya
Attach a custom policy to a RAM user — konfigurasikan izin yang diperlukan