Cara mengunggah file lokal ke OSS menggunakan perintah cp - Object Storage Service

Untuk mengunggah file lokal, gambar, video, atau resource lainnya ke OSS—termasuk file berukuran besar—gunakan perintah cp di ossutil.

Catatan penting

Untuk mengunggah file, Anda harus memiliki izin oss:PutObject, oss:ListParts, dan oss:AbortMultipartUpload. Untuk detailnya, lihat Berikan kebijakan izin kustom kepada Pengguna RAM.
Unggah batch hanya didukung jika sumber berupa direktori.
Opsi --snapshot-path yang tersedia di ossutil 1.0 telah dihapus di ossutil 2.0. Untuk melakukan unggah inkremental, gunakan opsi -u (--update) sebagai gantinya.
Saat menggunakan opsi -u, --update, sistem mengirim setidaknya satu permintaan HEAD untuk setiap file guna membandingkannya dengan objek tujuan, terlepas dari apakah objek tersebut sudah ada atau belum. Dalam skenario di mana data jarang berubah, hal ini menghasilkan banyak permintaan yang tidak efisien, sehingga dapat menurunkan performa dan menimbulkan biaya tambahan. Evaluasi kebutuhan bisnis Anda secara cermat sebelum menggunakan opsi ini untuk menghindari konsumsi resource yang tidak perlu.

Sintaks perintah

ossutil cp source dest [flags]

Penting

Mulai dari ossutil 2.3.0, opsi --job, --parallel, --bigfile-threshold, --part-size, dan --write-buffer-size dapat dikonfigurasi melalui file konfigurasi. Tambahkan dalam format key=value (misalnya, job=10) pada bagian profil yang sesuai di file konfigurasi, atau atur menggunakan ossutil config set. Opsi baris perintah memiliki prioritas lebih tinggi daripada pengaturan file konfigurasi.
Mulai dari ossutil 2.4.0, opsi --enable-symlink-dir ditambahkan untuk mendukung pengunggahan subdirektori symlink menggunakan perintah cp.

Parameter	Tipe	Deskripsi
source	string	Jalur file lokal. Mendukung jalur relatif, jalur mutlak, dan `-`. Jika diatur ke `-`, data dibaca dari standard input.
dest	string	Jalur file di bucket tujuan. Contoh: `oss://bucket[/prefix]`.
--acl	string	Izin akses untuk objek. Nilai yang valid: private: privat. public-read: baca-publik. public-read-write: baca-tulis publik. default: mewarisi dari bucket.
--bandwidth-limit	SizeSuffix	Membatasi bandwidth jaringan untuk mengontrol laju transfer data. Nilai minimum adalah 1024 B/s. Satuan default adalah B/s. Saat mengatur parameter ini, tentukan satuan sesuai kebutuhan. Satuan yang valid meliputi B (byte), K (kilobyte), M (megabyte), dan G (gigabyte). Misalnya, 50 M mengatur batas bandwidth menjadi 50 MB/s.
--bigfile-threshold	SizeSuffix	Ambang batas (dalam byte) untuk mengaktifkan unggah multi-bagian, unduh, atau copy untuk file besar. Nilai default: 104857600. Catatan Didukung pengaturan file konfigurasi sejak ossutil 2.3.0.
--cache-control	string	Menentukan perilaku cache saat objek diunduh oleh browser web.
--content-disposition	string	Menentukan cara objek ditampilkan.
--content-encoding	string	Menyatakan metode encoding objek.
--content-type	string	Tipe konten objek.
--copy-props	string	Menentukan properti mana yang akan dicopy dari objek sumber. Nilai yang valid: none metadata default
--checkpoint-dir	string	Jika jalur direktori checkpoint tidak ditentukan, unggah yang dapat dilanjutkan dinonaktifkan. Jika direktori ditentukan, unggah yang dapat dilanjutkan diaktifkan, dan file checkpoint disimpan di subdirektori `.ossutil_checkpoint` di bawah jalur yang ditentukan.
-d, --dirs	string	Daftar file dan subdirektori di direktori saat ini tanpa merekursif semua file di subdirektori.
--encoding-type	string	Metode encoding untuk nama objek atau nama file input. Nilai yang valid: url.
--end-with	string	Mengembalikan objek yang berada sebelum atau sesuai dengan nilai yang ditentukan dalam urutan alfabetis.
--exclude	stringArray	Aturan pengecualian untuk jalur atau nama file.
--exclude-from	stringArray	Baca aturan pengecualian dari file aturan.
--expires	stringArray	Menentukan waktu kedaluwarsa absolut untuk konten yang di-cache.
--files-from	stringArray	Baca daftar nama file sumber dari file, mengabaikan baris kosong dan baris komentar. Hanya berlaku untuk skenario penyaringan.
--files-from-raw	stringArray	Baca daftar nama file sumber dari file. Hanya berlaku untuk skenario penyaringan.
--filter	stringArray	Aturan penyaringan untuk jalur atau nama file.
--filter-from	stringArray	Baca aturan penyaringan dari file aturan.
-f, --force	/	Paksa operasi tanpa meminta konfirmasi.
--include	stringArray	Aturan inklusi untuk jalur atau nama file. Catatan Untuk informasi lebih lanjut tentang opsi penyaringan, lihat Opsi penyaringan.
--include-from	stringArray	Baca aturan inklusi dari file aturan.
-j, --job	int	Jumlah tugas konkuren. Nilai default: 3. Catatan Opsi ini hanya berlaku jika Anda juga menentukan salah satu parameter berikut: `-f`, `--update`, `--size-only`, atau `--ignore-existing`. Didukung pengaturan file konfigurasi sejak ossutil 2.3.0.
--listObjects	/	Gunakan API ListObjects untuk mendaftar objek.
--max-size	SizeSuffix	Ukuran file maksimum untuk ditransfer. Satuan default adalah byte. Anda juga dapat menggunakan sufiks: B\|K\|M\|G\|T\|P. Catatan: 1K (KiB) = 1024B.
--metadata	strings	Metadata yang ditentukan pengguna untuk objek, dalam format key=value.
--metadata-directive	string	Menentukan cara mengatur metadata untuk objek tujuan. Nilai yang valid: COPY REPLACE
--metadata-exclude	stringArray	Aturan pengecualian untuk metadata objek.
--metadata-filter	stringArray	Aturan penyaringan untuk metadata objek.
--metadata-filter-from	stringArray	Baca aturan penyaringan metadata objek dari file aturan.
--metadata-include	stringArray	Aturan inklusi untuk metadata objek.
--min-age	Duration	Hanya unggah file yang dimodifikasi sebelum interval waktu yang ditentukan. Satuan default adalah detik. Anda dapat menggunakan sufiks seperti h (jam). Contoh: 1h berarti 1 jam. Catatan `--min-age 1h` hanya mengunggah file yang dimodifikasi satu jam yang lalu atau lebih awal.
--max-age	Duration	Hanya unggah file yang dimodifikasi dalam interval waktu yang ditentukan. Satuan default adalah detik. Anda dapat menggunakan sufiks seperti h (jam). Contoh: 1h berarti 1 jam. Catatan `--max-age 1h` hanya mengunggah file yang dimodifikasi dalam satu jam terakhir.
--min-mtime	Time	Hanya unggah file yang dimodifikasi setelah waktu yang ditentukan, misalnya, 2006-01-02T15:04:05.
--max-mtime	Time	Hanya unggah file yang dimodifikasi sebelum waktu yang ditentukan, misalnya, 2006-01-02T15:04:05.
--min-size	SizeSuffix	Ukuran file minimum untuk ditransfer. Satuan default adalah byte. Anda juga dapat menggunakan sufiks: B\|K\|M\|G\|T\|P. Catatan: 1K (KiB) = 1024B.
--no-progress	/	Jangan tampilkan bilah progres.
--page-size	int	Jumlah maksimum objek yang didaftar per halaman selama unggah batch. Nilai default: 1000. Rentang valid: 1–1000.
--parallel	int	Jumlah tugas konkuren untuk operasi internal pada satu file. Catatan Didukung pengaturan file konfigurasi sejak ossutil 2.3.0.
--part-size	SizeSuffix	Ukuran bagian untuk unggah multi-bagian. Secara default, ossutil menghitung ukuran bagian yang sesuai berdasarkan ukuran file. Rentang valid: 100 KiB–5 GiB. Catatan Didukung pengaturan file konfigurasi sejak ossutil 2.3.0.
-r, --recursive	/	Lakukan operasi secara rekursif. Saat opsi ini ditentukan, perintah beroperasi pada semua objek yang cocok di bucket. Jika tidak, perintah hanya beroperasi pada objek yang ditentukan oleh jalur.
--request-payer	string	Metode pembayaran untuk permintaan. Atur parameter ini jika bucket menggunakan mode bayar-per-permintaan. Nilai yang valid: requester.
--size-only	/	Hanya unggah file sumber yang ukurannya berbeda dari file tujuan.
--storage-class	string	Kelas penyimpanan objek. Nilai yang valid: Standard: Penyimpanan Standar. IA: Penyimpanan akses jarang. Archive: Archive Storage. ColdArchive: Penyimpanan Arsip Dingin. DeepColdArchive: Deep Cold Archive storage.
--tagging	strings	Tag untuk objek, dalam format key=value.
--tagging-directive	string	Menentukan cara mengatur tag untuk objek tujuan. Nilai yang valid: COPY REPLACE
-u, --update	/	Melewati file yang sudah ada di tujuan dan memiliki waktu modifikasi lebih baru daripada file sumber. Catatan Jika file sudah ada di tujuan tetapi memiliki waktu modifikasi lebih lama daripada file sumber, file tersebut diperbarui.
--ignore-existing	/	Melewati file yang sudah ada di tujuan.
--enable-symlink-dir	/	Mengikuti dan mengunggah subdirektori symbolic link (symlink) selama proses unggah. Secara default, perintah cp melewati subdirektori symlink saat mengunggah direktori. Saat opsi ini ditentukan, perintah secara rekursif mengunggah isi subdirektori symlink. Catatan Didukung sejak ossutil 2.4.0.

Catatan

Untuk informasi lebih lanjut, lihat Opsi baris perintah.

Aturan penamaan objek adalah sebagai berikut:

Untuk unggah file tunggal, jika awalan kosong, nama objek adalah nama file.
Untuk unggah file tunggal, jika awalan diakhiri dengan "/", nama objek adalah awalan + nama file.
Untuk unggah batch, jika awalan kosong, nama objek adalah jalur relatif file sumber.
Untuk unggah batch, jika awalan diakhiri dengan "/", nama objek adalah awalan + jalur relatif file sumber.
Untuk unggah batch, jika awalan tidak diakhiri dengan "/", nama objek adalah awalan + "/" + jalur relatif file sumber.

Catatan

Jalur relatif file sumber dimulai setelah Direktori root. Misalnya, saat menjalankan cp /root/dir/ ..., jalur relatif file /root/dir/subdir/test.txt adalah subdir/test.txt.

Parameter yang direkomendasikan untuk unggah file besar

Saat mengunggah file yang lebih besar dari 100 MB, ossutil secara otomatis beralih ke unggah multi-bagian. Untuk meningkatkan kecepatan unggah dan mengaktifkan unggah yang dapat dilanjutkan, gunakan parameter berikut secara bersamaan:

Parameter	Nilai yang direkomendasikan	Deskripsi
`-j, --job`	`10`	Jumlah tugas konkuren untuk mengunggah beberapa file. Nilai default: 3. Opsi ini hanya berlaku jika Anda juga menentukan `-f`, `--update`, `--size-only`, atau `--ignore-existing`.
`--parallel`	`10`	Jumlah tugas konkuren untuk operasi internal (seperti unggah multi-bagian) pada satu file. Meningkatkan nilai ini mempercepat unggah satu file besar.
`--checkpoint-dir`	`/path/to/checkpoint`	Direktori yang digunakan untuk unggah yang dapat dilanjutkan.

Direktori yang ditentukan oleh --checkpoint-dir dibuat di server lokal, bukan di bucket OSS. ossutil secara otomatis membuat subdirektori .ossutil_checkpoint di bawah jalur ini untuk menyimpan file checkpoint .ucp yang mencatat progres unggah (termasuk ID unggah multi-bagian dan informasi bagian).

Jika unggah terganggu, jalankan perintah yang sama lagi. ossutil melanjutkan unggah dari file checkpoint, menggunakan kembali ID unggah multi-bagian yang sama, dan tidak mengunggah ulang bagian yang sudah diunggah.

Contoh:

ossutil cp localfile.tar oss://examplebucket/desfolder/ -j 10 --parallel 10 --checkpoint-dir /path/to/checkpoint

Contoh

Unggah satu file

Unggah satu file

Unggah file lokal examplefile.txt ke folder desfolder di examplebucket.
```
ossutil cp D:/localpath/examplefile.txt oss://examplebucket/desfolder/
```

Unggah beberapa file

Unggah hanya file dalam folder

Unggah file dari folder lokal localfolder ke folder desfolder di examplebucket.
```
ossutil cp -r D:/localpath/localfolder/ oss://examplebucket/desfolder/
```

Unggah batch file yang sesuai kondisi

Unggah semua file dengan format file TXT.

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

Gunakan 10 tugas konkuren untuk unggah batch

ossutil cp -r D:/localpath/localfolder/ oss://examplebucket/desfolder/ -f -j 10

Batasi kecepatan unggah

Unggah file lokal upload.rar ke folder desfolder di examplebucket dengan kecepatan 20 MB/s. Satuan default adalah byte per detik (B/s).
```
ossutil cp D:/upload.rar oss://examplebucket/desfolder/ --bandwidth-limit 20971520
```
Unggah file lokal file.rar ke folder desfolder di examplebucket, membatasi kecepatan unggah hingga 50 MB/s. Tentukan satuan sebagai megabyte per detik (MB/s).
```
ossutil cp D:/file.rar oss://examplebucket/desfolder/ --bandwidth-limit 50M
```