All Products
Search

This Product

    Object Storage Service:cp (unggah file)

    Document Center

    Object Storage Service:cp (unggah file)

    Last Updated:May 28, 2026

    Unggah file atau direktori lokal ke bucket OSS dengan perintah cp. Perintah ini mendukung unggah simple, unggah yang dapat dilanjutkan, unggah batch, dan unggah inkremental, serta menyediakan opsi untuk mengatur metadata objek, kelas penyimpanan, dan ACL.

    Cara kerja

    Perintah cp memilih metode unggah berdasarkan ukuran file:

    • Simple upload: Digunakan ketika ukuran file lebih kecil dari ambang batas unggah yang dapat dilanjutkan (default: 100 MB), yang dapat dikonfigurasi melalui opsi --bigfile-threshold.

    • Resumable upload: Digunakan ketika ukuran file mencapai atau melebihi ambang batas tersebut. Unggahan yang terputus akan meninggalkan bagian-bagian di bucket. Bersihkan bagian-bagian ini secara berkala untuk menghindari biaya penyimpanan. Anda dapat secara manual menghapus bagian-bagian tersebut atau mengonfigurasi aturan siklus hidup untuk penghapusan otomatis.

    Catatan

    Mulai dari ossutil v1.6.16, Anda dapat menggunakan ossutil sebagai nama biner di semua sistem operasi yang didukung. Pada versi sebelumnya, Anda harus menggunakan nama biner spesifik OS untuk sistem Anda. Untuk informasi selengkapnya, lihat referensi perintah ossutil.

    Izin

    Akun Alibaba Cloud memiliki izin penuh secara default. Pengguna RAM dan Peran RAM tidak memiliki izin default dan memerlukan otorisasi melalui kebijakan RAM atau kebijakan bucket.

    Aksi API

    Deskripsi

    oss:PutObject

    Mengunggah objek.

    oss:PutObjectTagging

    Diperlukan hanya saat menetapkan tag objek selama unggah.

    kms:GenerateDataKey

    Diperlukan hanya saat menggunakan Enkripsi sisi server Key Management Service (KMS).

    kms:Decrypt

    Sintaks perintah

    ossutil cp file_url cloud_url [options]

    Parameter dan opsi:

    Parameter

    Deskripsi

    file_url

    Jalur file lokal. Jika sumbernya adalah direktori, jalurnya harus diakhiri dengan pemisah jalur (/ atau \). Contohnya, /localfolder/examplefile.txt pada sistem Linux atau D:\localfolder\examplefile.txt pada sistem Windows.

    cloud_url

    Jalur objek, dalam format oss://bucket[/prefix]. Contoh: oss://examplebucket/examplefile.txt.

    -r, --recursive

    Mengunggah file dan subdirektori secara rekursif. Tanpa opsi ini, hanya objek yang ditentukan yang diproses.

    -f --force

    Memaksa operasi berjalan tanpa prompt konfirmasi.

    -u, --update

    Hanya mengunggah jika objek tujuan tidak ada atau lebih lama daripada file sumber.

    --maxupspeed

    Kecepatan unggah maksimum dalam KB/s. Default: 0 (tidak terbatas).

    --enable-symlink-dir

    Mengunggah subdirektori yang ditautkan. Opsi ini dinonaktifkan secara default.

    --disable-all-symlink

    Mengabaikan semua tautan simbolik selama unggah.

    --disable-ignore-error

    Tidak mengabaikan error selama operasi batch.

    --only-current-dir

    Hanya mengunggah file dalam direktori sumber yang ditentukan, mengabaikan subdirektorinya.

    --bigfile-threshold

    Ambang batas ukuran untuk unggah yang dapat dilanjutkan. Satuan: byte.

    Nilai default: 100 MB

    Nilai valid: 0 hingga 9223372036854775807

    --part-size

    Ukuran bagian dalam byte. Secara default, ossutil menghitung nilai ini berdasarkan ukuran file. 

    Rentang: 1 hingga 9223372036854775807

    --checkpoint-dir

    Direktori untuk catatan unggah yang dapat dilanjutkan. Secara default, ossutil membuat direktori .ossutil_checkpoint dan menghapusnya setelah unggah berhasil. Jika Anda menentukan direktori kustom, pastikan direktori tersebut dapat dihapus.

    --encoding-type

    Encoding nama file. Atur ke url untuk melakukan URL-encode pada nama file. Tidak di-encode secara default.

    --include

    Menyertakan semua file yang memenuhi kondisi yang ditentukan. Untuk informasi selengkapnya tentang sintaks dan contoh, lihat Unggah batch file yang memenuhi kondisi tertentu.

    --exclude

    Menyingkirkan semua file yang memenuhi kondisi yang ditentukan. Untuk informasi selengkapnya tentang sintaks dan contoh, lihat Unggah batch file yang memenuhi kondisi tertentu.

    --meta

    Metadata file. Ini mencakup header HTTP standar dan metadata yang ditentukan pengguna, yang diawali dengan x-oss-meta-. Metadata harus dalam format header:nilai#header:nilai. Contoh: Cache-Control:no-cache#Content-Encoding:gzip. Untuk informasi selengkapnya tentang metadata yang didukung oleh OSS, lihat Mengelola metadata objek.

    --acl

    Daftar kontrol akses (ACL) file. Nilai valid:

    • default (default): ACL objek sama dengan ACL bucket.

    • private: Hanya pemilik bucket yang dapat membaca dan menulis objek di bucket tersebut. Pengguna lain tidak dapat mengakses objek tersebut.

    • public-read: Hanya pemilik bucket yang dapat menulis objek di bucket tersebut. Pengguna lain, termasuk pengguna anonim, dapat membaca objek tersebut. Hal ini dapat menyebabkan kebocoran data dan biaya tak terduga yang tinggi. Jika pengguna jahat menulis informasi ilegal ke objek tersebut, hak dan kepentingan sah Anda mungkin dilanggar. Jangan mengonfigurasi izin ini kecuali dalam skenario khusus.

    • public-read-write: Siapa pun, termasuk pengguna anonim, dapat membaca dan menulis objek di bucket tersebut. Hal ini dapat menyebabkan kebocoran data dan biaya tak terduga yang tinggi. Berhati-hatilah saat mengonfigurasi izin ini.

    --snapshot-path

    Direktori untuk snapshot unggah. Pada unggahan berikutnya, ossutil membaca direktori ini untuk melakukan unggah inkremental.

    --disable-crc64

    Menonaktifkan validasi data CRC-64. Diaktifkan secara default.

    --disable-dir-object

    Melewati pembuatan objek direktori selama unggah.

    --payer

    Metode pembayaran. Atur ke requester untuk membebankan biaya traffic dan permintaan kepada pihak yang meminta.

    --tagging

    Tag yang akan ditambahkan selama unggah. Format: TagkeyA=TagvalueA&TagkeyB=TagvalueB.....

    -j, --jobs

    Tugas konkuren untuk operasi multi-file. Default: 3. Nilai valid: 1 hingga 10000.

    --parallel

    Tugas konkuren untuk operasi single-file. Nilai valid: 1 hingga 10000. Ditentukan secara otomatis berdasarkan jenis operasi dan ukuran file jika tidak diatur.

    --start-time

    Stempel waktu UNIX. Objek yang terakhir diperbarui sebelum waktu ini diabaikan.

    Catatan

    Hanya ossutil 1.7.18 dan versi yang lebih baru yang mendukung parameter ini. Untuk informasi selengkapnya tentang peningkatan, lihat update (Upgrade ossutil).

    --end-time

    Stempel waktu UNIX. Objek yang terakhir diperbarui setelah waktu ini diabaikan.

    Catatan

    • Jika Anda menentukan `start-time` dan `end-time`, perintah copy hanya dijalankan untuk file yang dimodifikasi terakhir antara waktu mulai dan akhir yang ditentukan.

    • Hanya ossutil 1.7.18 dan versi yang lebih baru yang mendukung parameter ini. Untuk informasi selengkapnya tentang cara meningkatkan versi, lihat update (Upgrade ossutil).

    Untuk informasi selengkapnya tentang opsi umum lainnya untuk perintah ini, lihat Opsi umum.

    Atur -j, --jobs dan --parallel untuk menyesuaikan performa. Secara default, ossutil menghitung nilai parallel berdasarkan ukuran file. Untuk transfer batch file besar, konkurensi aktual adalah jobs × parallel.

    • Jika mesin memiliki sumber daya terbatas (bandwidth, memori, atau CPU), kurangi konkurensi menjadi 100 atau kurang. Tingkatkan jika sumber daya belum dimanfaatkan secara optimal.

    • Konkurensi berlebihan dapat menurunkan performa atau menyebabkan error EOF. Sesuaikan -j, --jobs dan --parallel berdasarkan sumber daya mesin Anda. Mulailah dari nilai rendah dan tingkatkan secara bertahap untuk menemukan nilai optimal.

    Contoh

    Contoh-contoh ini menggunakan Linux. Sesuaikan jalur sesuai OS Anda. Contoh-contoh ini mengasumsikan:

    • Nama bucket: examplebucket

    • Direktori OSS: desfolder/

    • Direktori lokal: localfolder/

    • File lokal: examplefile.txt

    Unggah satu file

    • Unggah file ke direktori. Jika nama objek tidak ditentukan, nama file asli digunakan.

      ossutil cp examplefile.txt oss://examplebucket/desfolder/

    • Unggah satu file dan gunakan opsi --meta untuk mengatur metadata-nya. Metadata harus dalam format header:value#header:value....

      ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip

    Unggah batch

    • Hanya mengunggah file dalam folder

      Tambahkan opsi -r ke perintah cp untuk hanya mengunggah file dari folder lokal ke jalur tertentu di OSS. 

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/

    • Unggah file dari folder dan tentukan stempel waktu

      Unggah file dari folder lokal ke jalur OSS tertentu. File-file tersebut harus dimodifikasi antara pukul 10:09:18 (UTC+8) hingga 12:55:58 (UTC+8) pada 31 Oktober 2023.

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158

    • Unggah folder dan file-file di dalamnya

      Gunakan opsi cp -r untuk mengunggah folder lokal beserta seluruh isinya. OSS membuat objek 0 KB yang diakhiri dengan / untuk setiap subdirektori, tetapi tidak untuk folder tersebut sendiri. Untuk membuat objek folder, gunakan perintah mkdir (buat direktori).

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/

    • Unggah folder dan lewati file yang sudah ada

      Untuk mencoba ulang unggah batch yang gagal, gunakan --update (atau -u) untuk melewati file yang sudah diunggah dan melakukan unggah inkremental:

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u

    • Hanya mengunggah file dalam direktori saat ini dan mengabaikan subdirektori 

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r

    • Unggah tanpa membuat objek untuk direktori

      Di OSS, direktori disimulasikan oleh objek 0 KB yang diakhiri dengan /. Gunakan --disable-dir-object untuk melewati pembuatan objek tersebut. Struktur direktori tetap muncul di Konsol OSS tetapi akan menghilang ketika semua file di dalamnya dihapus.

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r

    • Unggah file dalam subdirektori yang ditautkan 

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r

    • Abaikan semua subfile dan subdirektori yang ditautkan selama unggah 

      ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

    Unggah batch file yang memenuhi kondisi tertentu

    Gunakan --include dan --exclude untuk memfilter file selama unggah batch.

    Opsi --include dan --exclude mendukung format berikut:

    • Asterisk (*): Mencocokkan sejumlah karakter apa pun. Misalnya, *.txt mencocokkan semua file TXT.

    • Tanda tanya (?): Mencocokkan satu karakter. Misalnya, abc?.jpg mencocokkan semua file JPG yang namanya "abc" diikuti satu karakter, seperti abc1.jpg.

    • [sequence]: Mencocokkan karakter apa pun dalam urutan tersebut. Misalnya, abc[1-5].jpg mencocokkan file bernama abc1.jpg hingga abc5.jpg.

    • [!sequence]: Mencocokkan karakter apa pun di luar urutan tersebut. Misalnya, abc[!0-7].jpg mencocokkan file yang namanya bukan abc0.jpg hingga abc7.jpg.

    Satu aturan dapat berisi beberapa kondisi include dan exclude. ossutil mengevaluasinya dari kiri ke kanan. Untuk file bernama test.txt, urutan aturan yang berbeda menghasilkan hasil yang berbeda.

    • Aturan 1: --include "*test*" --exclude "*.txt" . Saat aturan cocok dengan --include "*test*", hasilnya adalah bahwa test.txt memenuhi kondisi. Saat aturan melanjutkan ke --exclude "*.txt", test.txt dikecualikan karena nama filenya mengandung .txt. Hasil akhirnya adalah bahwa test.txt tidak memenuhi kondisi.

    • Aturan 2: --exclude "*.txt" --include "*test*". File test.txt dikecualikan oleh aturan --exclude "*.txt". Namun, aturan --include "*test*" kemudian menyertakan test.txt karena nama filenya mengandung "test". Akibatnya, test.txt disertakan.

    • Aturan 3: --include "*test*" --exclude "*.txt" --include "te?t.txt" . Pertama, aturan --include "*test*" menyertakan test.txt. Selanjutnya, aturan --exclude "*.txt" mengecualikan test.txt. Terakhir, aturan --include "te?t.txt" menyertakan test.txt. Oleh karena itu, test.txt disertakan.

    Penting

    Anda tidak dapat menentukan format direktori dalam kondisi tersebut. Misalnya, --include "/usr/test/.jpg" tidak didukung.

    Berikut adalah beberapa contoh:

    • Unggah semua file dalam format TXT 

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r

    • Unggah semua file yang namanya mengandung abc dan bukan dalam format JPG atau TXT 

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

    Batasi kecepatan unggah

    Gunakan --maxupspeed untuk membatasi kecepatan unggah dalam KB/s. Contoh:

    • Unggah file dan atur batas kecepatan menjadi 1 MB/s

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024

    • Unggah folder dan atur batas kecepatan menjadi 1 MB/s 

      ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

    Unggah dan atur tag objek

    Gunakan --tagging untuk mengatur tag objek selama unggah. Pisahkan beberapa tag dengan tanda ampersand (&). Contoh:

    ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&..."

    Penandaan objek.

    Unggah dan tentukan kelas penyimpanan

    Gunakan --meta untuk mengatur kelas penyimpanan selama unggah. Nilai valid:

    • Standard: Standard

    • IA: Infrequent Access

    • Archive: Archive Storage

    • ColdArchive: Cold Archive

    • DeepColdArchive: Deep Cold Archive

    Jika kelas penyimpanan tidak ditentukan, objek mewarisi kelas penyimpanan bucket. Untuk informasi selengkapnya, lihat Kelas penyimpanan.

    Berikut adalah contoh mengunggah file dan menentukan kelas penyimpanan:

    • Unggah satu file dan atur kelas penyimpanannya menjadi Infrequent Access 

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA

    • Unggah folder dan atur kelas penyimpanan file-file di dalamnya menjadi Standard 

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

    Unggah dan tentukan ACL

    Gunakan --acl untuk mengatur ACL file yang diunggah. Nilai valid:

    • default: mewarisi ACL bucket (default)

    • private: private

    • public-read: public-read

    • public-read-write: Akses baca dan tulis publik

    Berikut adalah contohnya:

    • Unggah satu file dan atur ACL-nya menjadi private

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private

    • Unggah folder dan atur ACL file-file di dalamnya menjadi public-read

      ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r

    Unggah dan tentukan metode enkripsi

    Tentukan metode enkripsi sisi server selama unggah. Contoh:

    • Unggah file dan tentukan SSE-OSS sebagai metode enkripsi serta AES256 sebagai algoritma enkripsi

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256

    • Unggah file dan tentukan SSE-KMS sebagai metode enkripsi dan jangan tentukan ID CMK

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS

      Enkripsi KMS menimbulkan biaya penggunaan kunci kecil. Harga KMS.

    • Unggah file dan tentukan SSE-KMS sebagai metode enkripsi dan ID CMK

      ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

    Untuk informasi selengkapnya tentang enkripsi sisi server, lihat Enkripsi sisi server.

    Unggah dan buat snapshot

    Dengan --snapshot-path, ossutil mencatat lastModifiedTime file yang diunggah dan menggunakannya untuk melewati file yang tidak berubah pada unggahan berikutnya, sehingga mempercepat unggah batch inkremental. Pastikan tidak ada pengguna lain yang memodifikasi objek terkait di antara unggahan. Opsi --snapshot-path paling cocok untuk unggah batch besar. Contoh:

    ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path
    Penting

    • ossutil tidak menghapus snapshot secara otomatis di folder snapshot-path. Hapus secara berkala snapshot yang tidak diperlukan dari folder snapshot-path.

    • I/O snapshot menambahkan overhead. Untuk batch kecil, kondisi jaringan baik, atau objek bersama, gunakan opsi --update sebagai gantinya untuk unggah inkremental.

    • Anda dapat menggunakan opsi --update dan --snapshot-path secara bersamaan. ossutil pertama-tama memeriksa informasi snapshot-path untuk menentukan apakah file akan dilewati. Jika file tidak dilewati berdasarkan snapshot, ossutil kemudian menggunakan opsi --update untuk menentukan apakah file akan dilewati.

    Unggah dan konfigurasi bayar-per-permintaan

    ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester

    Unggah lintas akun atau lintas wilayah

    Gunakan opsi umum -e, -i, dan -k untuk mengunggah file lokal ke bucket di wilayah berbeda atau di bawah Akun Alibaba Cloud yang berbeda.

    Catatan

    Tentukan titik akhir yang sesuai dengan wilayah bucket. Untuk informasi selengkapnya, lihat Wilayah dan Titik Akhir.

    ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret