ossutil cp - Upload files and directories to OSS - Object Storage Service

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 menetapkan metadata objek, kelas penyimpanan, dan ACL.

Cara kerja

Perintah cp memilih metode unggah berdasarkan ukuran file:

Simple upload: Digunakan ketika file lebih kecil dari ambang batas unggah yang dapat dilanjutkan (default: 100 MB, dapat dikonfigurasi dengan --bigfile-threshold).
Resumable upload: Digunakan ketika file mencapai atau melebihi ambang batas tersebut. Unggahan yang terputus 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.

API Action	Description
`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	Description
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 khusus, pastikan direktori tersebut dapat dihapus.
--encoding-type	Pengkodean nama file. Atur ke url untuk meng-encode nama file dalam format URL. Tidak di-encode secara default.
--include	Menyertakan semua file yang memenuhi kondisi tertentu. Untuk informasi selengkapnya tentang sintaks dan contoh, lihat Unggah batch file yang memenuhi kondisi tertentu.
--exclude	Mengecualikan semua file yang memenuhi kondisi tertentu. 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 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 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.

Sesuaikan -j, --jobs dan --parallel untuk mengoptimalkan performa. Secara default, ossutil menghitung 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 berikut 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 menetapkan metadata file. Metadata harus dalam format header:nilai#header:nilai....
```
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/
```
Mengunggah file dari folder dan menentukan 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
```
Mengunggah 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/
```
Mengunggah folder dan melewati 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

Mengunggah 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 hilang ketika semua file di dalamnya dihapus.
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
```

Mengunggah file dalam subdirektori yang ditautkan

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

Mengabaikan semua subfile dan subdirektori yang ditautkan selama unggah

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

Secara default, perintah cp mengikuti tautan simbolik dan mengunggah konten file yang ditunjuk oleh tautan simbolik tersebut, bukan tautan simbolik itu sendiri.

Sebagai contoh, link.txt adalah tautan simbolik yang menunjuk ke source.txt:
```
ossutil cp link.txt oss://examplebucket/
```
Setelah unggah, konten objek di OSS sesuai dengan konten source.txt. Perilaku ini sama untuk unggah file tunggal maupun unggah direktori rekursif (-r).

Opsi --disable-all-symlink dan --enable-symlink-dir hanya tersedia di ossutil 1.x. Di ossutil 2.x, ossutil mengikuti tautan simbolik secara default dan tidak menyediakan opsi untuk menonaktifkan perilaku ini.

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 (*): 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 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 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:

Mengunggah semua file dalam format TXT

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

Mengunggah 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 menetapkan 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 menetapkan 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 存储类型.

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 menetapkan ACL file yang diunggah. Nilai valid:

default: mewarisi ACL bucket (default)
private: private
public-read: public-read
public-read-write: Akses baca-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 dikenai 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. --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 --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 harus dilewati. Jika file tidak dilewati berdasarkan snapshot, ossutil kemudian menggunakan opsi --update untuk menentukan apakah file harus dilewati.

Unggah dan konfigurasikan 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 endpoint yang sesuai dengan wilayah bucket tersebut. Untuk informasi selengkapnya, lihat Wilayah dan endpoint.

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