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

Gunakan perintah cp untuk mengunggah file atau direktori lokal ke bucket tertentu. Perintah ini mendukung unggahan sederhana, unggahan yang dapat dilanjutkan, unggahan batch, dan unggahan inkremental. Anda juga dapat menentukan metadata objek, kelas penyimpanan, serta daftar kontrol akses (ACL) selama proses unggah.

Cara kerja

Saat menggunakan perintah cp untuk mengunggah file, ossutil secara otomatis memilih metode unggah berdasarkan ukuran file:

Simple upload: Digunakan untuk file yang lebih kecil dari ambang batas unggah yang dapat dilanjutkan. Ambang batas default adalah 100 MB, yang dapat diubah menggunakan opsi --bigfile-threshold.
Resumable upload: Digunakan untuk file yang ukurannya lebih besar dari atau sama dengan ambang batas tersebut. Jika unggahan terganggu, bagian-bagian yang telah diunggah akan disimpan sementara di bucket. Untuk menghindari biaya penyimpanan, Anda harus membersihkan bagian-bagian ini secara berkala, baik secara manual melalui penghapusan bagian tersebut maupun dengan mengonfigurasi aturan siklus hidup untuk penghapusan otomatis.

Catatan

Mulai dari versi ossutil 1.6.16, Anda dapat menggunakan ossutil sebagai nama biner di semua sistem operasi yang didukung. Pada versi sebelumnya, Anda harus menggunakan nama biner spesifik sistem operasi. Untuk informasi lebih lanjut, lihat referensi perintah ossutil.

Izin

Secara default, akun Alibaba Cloud memiliki izin penuh untuk semua operasi. Namun, pengguna Resource Access Management (RAM) atau peran RAM tidak memiliki izin secara default. Pemilik akun Alibaba Cloud atau administrator harus memberikan izin melalui kebijakan RAM atau kebijakan bucket.

Aksi API	Deskripsi
`oss:PutObject`	Mengunggah objek.
`oss:PutObjectTagging`	Opsional. Diperlukan saat Anda mengunggah objek dan menetapkan tag-nya.
`kms:GenerateDataKey`	Opsional. Diperlukan saat Anda mengunggah objek dan mengaktifkan enkripsi sisi server dengan KMS.
`kms:Decrypt`

Sintaksis perintah

ossutil cp file_url cloud_url [options]

Tabel berikut menjelaskan parameter dan opsi tersebut.

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	Menjalankan operasi secara rekursif. Saat Anda menentukan opsi ini, ossutil menjalankan operasi pada semua objek yang cocok di dalam bucket. Jika tidak, ossutil hanya menjalankan operasi pada objek tunggal yang ditentukan.
-f --force	Memaksa operasi berjalan tanpa prompt konfirmasi.
-u，--update	Hanya mengunggah file jika objek tujuan tidak ada atau jika file sumber dimodifikasi lebih baru daripada objek tujuan.
--maxupspeed	Kecepatan unggah maksimum. Satuan: KB/s. Nilai default adalah 0, yang berarti kecepatan unggah tidak dibatasi.
--enable-symlink-dir	Mengunggah subdirektori yang ditautkan. Opsi ini dinonaktifkan secara default.
--disable-all-symlink	Mengabaikan semua subfile dan subdirektori yang ditautkan selama unggahan.
--disable-ignore-error	Tidak mengabaikan error selama operasi batch.
--only-current-dir	Hanya mengunggah file di direktori sumber yang ditentukan, mengabaikan subdirektorinya.
--bigfile-threshold	Ambang batas ukuran untuk unggahan yang dapat dilanjutkan. Satuan: byte. Nilai default: 100 MB Nilai valid: 0 hingga 9223372036854775807
--part-size	Ukuran setiap bagian. Satuan: byte. Secara default, ossutil menghitung ukuran bagian yang sesuai berdasarkan ukuran file. Nilai valid: 1 hingga 9223372036854775807
--checkpoint-dir	Direktori tempat menyimpan catatan unggahan yang dapat dilanjutkan. Jika unggahan yang dapat dilanjutkan gagal, ossutil secara otomatis membuat direktori bernama `.ossutil_checkpoint` dan mencatat informasi checkpoint di dalamnya. Setelah unggahan berhasil, direktori tersebut dihapus. Jika Anda menentukan opsi ini, pastikan direktori yang ditentukan dapat dihapus.
--encoding-type	Format encoding nama file. Tetapkan nilainya ke url. Jika Anda tidak menentukan opsi ini, nama file tidak di-encode.
--include	Menyertakan semua file yang memenuhi kondisi tertentu. Untuk informasi lebih lanjut tentang sintaksis dan contoh, lihat Unggah file batch yang memenuhi kondisi tertentu.
--exclude	Menyingkirkan semua file yang memenuhi kondisi tertentu. Untuk informasi lebih lanjut tentang sintaksis dan contoh, lihat Unggah file batch 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:value#header:value`. Contoh: `Cache-Control:no-cache#Content-Encoding:gzip`. Untuk informasi lebih lanjut tentang metadata yang didukung oleh OSS, lihat Kelola 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 dalam bucket. Pengguna lain tidak dapat mengakses objek tersebut. public-read: Hanya pemilik bucket yang dapat menulis objek di dalam bucket. 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, 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 dalam bucket. Hal ini dapat menyebabkan kebocoran data dan biaya tak terduga yang tinggi. Gunakan dengan hati-hati saat mengonfigurasi izin ini.
--snapshot-path	Direktori tempat menyimpan informasi snapshot untuk file yang diunggah. Pada unggahan berikutnya, ossutil membaca informasi snapshot dari direktori yang ditentukan untuk melakukan unggahan inkremental.
--disable-crc64	Menonaktifkan validasi data pemeriksaan redundansi siklik 64-bit (CRC-64). Secara default, ossutil mengaktifkan validasi CRC-64 untuk transmisi data.
--disable-dir-object	Tidak membuat objek untuk direktori saat Anda mengunggah file.
--payer	Metode pembayaran untuk permintaan. Jika Anda ingin pihak peminta membayar biaya lalu lintas, permintaan, dan sumber daya lain yang dihasilkan dari mengakses jalur tertentu, tetapkan opsi ini ke requester.
--tagging	Tag yang akan ditambahkan ke objek selama unggahan. Formatnya adalah `TagkeyA=TagvalueA&TagkeyB=TagvalueB....`.
-j，--jobs	Jumlah tugas konkuren untuk operasi pada beberapa file. Nilai default adalah 3. Nilai valid: 1 hingga 10000.
--parallel	Jumlah tugas konkuren untuk operasi pada satu file. Nilai valid: 1 hingga 10000. Jika Anda tidak menyetel opsi ini, ossutil menentukan nilainya berdasarkan jenis operasi dan ukuran file.
--start-time	Stempel waktu UNIX. Objek yang terakhir dimodifikasi sebelum waktu ini diabaikan. Catatan Hanya ossutil versi 1.7.18 dan yang lebih baru yang mendukung parameter ini. Untuk informasi lebih lanjut tentang peningkatan, lihat update (Upgrade ossutil).
--end-time	Stempel waktu UNIX. Objek yang terakhir dimodifikasi setelah waktu ini diabaikan. Catatan Jika Anda menentukan `start-time` dan `end-time`, perintah copy hanya dijalankan untuk file yang terakhir dimodifikasi antara waktu awal dan akhir yang ditentukan. Hanya ossutil versi 1.7.18 dan yang lebih baru yang mendukung parameter ini. Untuk informasi lebih lanjut tentang cara meningkatkan versi, lihat update (Upgrade ossutil).

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

Jika jumlah default tugas konkuren tidak memenuhi kebutuhan performa Anda, Anda dapat menyesuaikan opsi -j, --jobs dan --parallel. Secara default, ossutil menghitung nilai opsi `parallel` berdasarkan ukuran file. Saat mentransfer file besar secara batch, jumlah aktual tugas konkuren adalah hasil perkalian antara nilai opsi `jobs` dan `parallel`.

Jika instans ECS atau server tempat menjalankan perintah memiliki sumber daya terbatas—seperti lebar pita jaringan, memori, atau CPU—Anda dapat mengurangi jumlah tugas konkuren menjadi 100 atau kurang. Sebaliknya, jika sumber daya belum dimanfaatkan secara optimal, Anda dapat meningkatkan jumlah tugas konkuren tersebut.
Jumlah tugas konkuren yang terlalu tinggi dapat menurunkan performa karena overhead switching thread dan persaingan sumber daya, bahkan menyebabkan error EOF. Sesuaikan opsi -j, --jobs dan --parallel berdasarkan sumber daya aktual mesin Anda. Saat melakukan uji stres, mulailah dengan jumlah tugas konkuren yang rendah dan tingkatkan secara bertahap hingga mencapai nilai optimal.

Contoh

Contoh berikut dijalankan pada sistem Linux. Sesuaikan parameter sesuai dengan sistem operasi dan lingkungan aktual Anda. Konvensi berikut digunakan dalam contoh:

Nama bucket: examplebucket
Direktori OSS: desfolder/
Direktori lokal: localfolder/
File lokal: examplefile.txt

Unggah satu file

Unggah file ke direktori tertentu dan gunakan nama file asli sebagai nama objek. Jika Anda tidak menentukan nama objek di OSS, nama file asli digunakan secara default. Jika Anda menentukan nama, objek disimpan dengan nama tersebut di OSS.
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```
Unggah satu file dan gunakan opsi --meta untuk menetapkan metadata file. 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
```

Unggahan 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 dalam rentang waktu tertentu
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 beserta file-file di dalamnya
Gunakan perintah cp dengan opsi -r untuk mengunggah folder lokal beserta seluruh isinya ke jalur OSS yang ditentukan. Untuk setiap subdirektori, OSS membuat objek 0 KB yang diakhiri dengan garis miring (/). Namun, OSS tidak membuat objek serupa untuk folder utama yang ditentukan. Untuk membuat objek tersebut, Anda dapat menggunakan perintah mkdir (membuat direktori).
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
```
Mengunggah folder dan melewati file yang sudah ada
Saat mencoba ulang unggahan batch yang gagal, Anda dapat menentukan opsi --update (atau -u) untuk melewati file yang berhasil diunggah dan melakukan unggahan inkremental. Contohnya:
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

Hanya mengunggah file di direktori saat ini dan mengabaikan subdirektori

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

Unggah tanpa membuat objek direktori
Di OSS, direktori direpresentasikan oleh objek 0 KB yang namanya diakhiri dengan garis miring (/). Saat mengunggah direktori, Anda dapat menambahkan parameter --disable-dir-object. Jika parameter ini ditambahkan, ossutil tidak membuat objek untuk direktori tersebut, tetapi struktur direktori tetap dapat dilihat di konsol OSS. Saat semua file di dalam direktori tersebut dihapus, direktori tersebut juga akan 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 unggahan

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

Unggah batch file yang memenuhi kondisi tertentu

Saat mengunggah file secara batch, Anda dapat menentukan opsi --include dan --exclude untuk hanya mengunggah file yang memenuhi kondisi tertentu.

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

Tanda bintang (*): Cocok dengan sejumlah karakter apa pun. Misalnya, *.txt cocok dengan semua file TXT.
Tanda tanya (?): Cocok dengan satu karakter. Misalnya, abc?.jpg cocok dengan semua file JPG yang namanya "abc" diikuti satu karakter, seperti abc1.jpg.
[sequence]: Cocok dengan karakter apa pun dalam urutan tersebut. Misalnya, abc[1-5].jpg cocok dengan file bernama abc1.jpg hingga abc5.jpg.
[!sequence]: Cocok dengan karakter apa pun di luar urutan tersebut. Misalnya, abc[!0-7].jpg cocok dengan file yang namanya bukan abc0.jpg hingga abc7.jpg.

Satu aturan dapat berisi beberapa kondisi include dan exclude. ossutil mencocokkan setiap file terhadap kondisi tersebut dari kiri ke kanan untuk menentukan apakah file tersebut disertakan atau dikecualikan. Sebagai contoh, pertimbangkan folder yang berisi file bernama test.txt. Aturan pencocokan yang berbeda menghasilkan hasil berikut.

Aturan 1: --include "*test*" --exclude "*.txt" . Saat aturan mencocokkan --include "*test*", hasilnya adalah test.txt memenuhi kondisi. Saat aturan melanjutkan pencocokan --exclude "*.txt", test.txt dikecualikan karena nama filenya mengandung .txt. Hasil akhirnya adalah test.txt tidak diunggah.
Aturan 2: --exclude "*.txt" --include "*test*". File test.txt pertama-tama dikecualikan oleh aturan --exclude "*.txt". Namun, aturan selanjutnya --include "*test*" menyertakan kembali test.txt karena nama filenya mengandung "test". Akibatnya, test.txt diunggah.
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 kembali test.txt. Oleh karena itu, test.txt diunggah.

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 unggahan

Saat mengunggah file, Anda dapat menggunakan opsi --maxupspeed untuk membatasi kecepatan unggah maksimum dalam KB/s. Berikut adalah contohnya:

Unggah file dan tetapkan batas kecepatan menjadi 1 MB/s

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

Unggah folder dan tetapkan batas kecepatan menjadi 1 MB/s

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

Unggah dan tetapkan tag objek

Saat mengunggah file, Anda dapat menggunakan opsi --tagging untuk menetapkan tag objek. Pisahkan beberapa tag dengan tanda ampersand (&). Berikut adalah contohnya:

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

Untuk informasi lebih lanjut tentang penandaan objek, lihat penandaan objek.

Unggah dan tentukan kelas penyimpanan

Saat mengunggah file, Anda dapat menggunakan opsi --meta untuk menetapkan kelas penyimpanannya. Nilai yang valid adalah:

Standard: Standard
IA: Infrequent Access
Archive: Archive Storage
ColdArchive: Cold Archive
DeepColdArchive: Deep Cold Archive

Jika Anda tidak menentukan kelas penyimpanan selama unggahan, objek tersebut mewarisi kelas penyimpanan bucket. Untuk informasi lebih lanjut, lihat Kelas penyimpanan.

Berikut adalah contoh mengunggah file dan menentukan kelas penyimpanan:

Unggah satu file dan tetapkan kelas penyimpanannya ke Infrequent Access

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

Unggah folder dan tetapkan kelas penyimpanan file-file di dalamnya ke Standard

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

Unggah dan tentukan ACL

Saat mengunggah file, Anda dapat menggunakan opsi --acl untuk menetapkan daftar kontrol akses (ACL)-nya. Nilai valid untuk ACL file adalah:

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 tetapkan ACL-nya ke private

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

Unggah folder dan tetapkan ACL file-file di dalamnya ke public-read

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

Unggah dan tentukan metode enkripsi

Saat mengunggah file, Anda dapat menentukan metode enkripsi sisi server untuk mengenkripsi file sebelum disimpan di bucket. Berikut adalah contohnya:

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, 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
```
Saat menggunakan enkripsi KMS, Anda dikenai biaya kecil untuk penggunaan kunci KMS. Untuk informasi lebih lanjut, lihat Harga KMS.

Unggah file dan tentukan SSE-KMS sebagai metode enkripsi serta 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 lebih lanjut tentang enkripsi sisi server, lihat Enkripsi sisi server.

Unggah dan buat snapshot

Saat mengunggah file secara batch, jika Anda menentukan opsi --snapshot-path, ossutil menghasilkan snapshot progres unggahan file di direktori yang ditentukan. Snapshot tersebut mencatat `lastModifiedTime` dari file lokal yang berhasil diunggah. Pada unggahan berikutnya, ossutil membandingkan `lastModifiedTime` untuk menentukan apakah file tersebut dilewati. Oleh karena itu, saat menggunakan opsi ini, pastikan tidak ada pengguna lain yang mengubah objek yang sesuai di OSS di antara dua unggahan tersebut. Opsi --snapshot-path cocok untuk mempercepat unggahan inkremental. Berikut adalah contohnya:

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

Penting

ossutil tidak secara otomatis menghapus informasi snapshot di direktori snapshot-path. Untuk mencegah informasi snapshot menjadi terlalu besar, Anda harus secara berkala menghapus snapshot yang tidak diperlukan dari direktori snapshot-path.
Membaca dan menulis informasi snapshot menimbulkan overhead tambahan. Jangan gunakan opsi ini jika Anda mengunggah jumlah file yang sedikit dalam batch, jika kondisi jaringan baik, atau jika pengguna lain sedang mengoperasikan objek yang sama. Untuk skenario tersebut, Anda dapat menggunakan opsi --update untuk unggahan inkremental.
Anda dapat menggunakan opsi --update dan --snapshot-path secara bersamaan. ossutil pertama-tama memeriksa informasi `snapshot-path` untuk menentukan apakah file tersebut dilewati. Jika file tidak dilewati berdasarkan snapshot, ossutil kemudian menggunakan opsi --update untuk menentukan apakah file tersebut dilewati.

Unggah dan konfigurasi pay-by-requester

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

Unggahan lintas akun atau lintas wilayah

Gunakan opsi umum -e, -i, dan -k untuk mengunggah file lokal exampleobject.txt ke direktori desfolder/ di bucket examplebucket. Bucket ini berlokasi di wilayah China (Shanghai) dan dimiliki oleh akun Alibaba Cloud lain.

Catatan

Anda harus menentukan endpoint yang sesuai dengan wilayah tempat bucket berada. Untuk informasi selengkapnya, lihat Wilayah dan endpoint.

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