全部产品
Search

搜索本产品

    Object Storage Service：cp (Unduhan objek)

    文档中心

    Object Storage Service：cp (Unduhan objek)

    更新时间：Nov 09, 2025

    Gunakan perintah cp untuk mengunduh sumber daya seperti file, gambar, dan video dari Object Storage Service (OSS) ke komputer lokal Anda. Perintah ini memungkinkan Anda mengunduh beberapa objek, membatasi kecepatan unduhan, atau mengunduh versi tertentu dari objek dari bucket yang memiliki pengendalian versi.

    Catatan penggunaan

    • Mulai dari ossutil 1.6.16, Anda dapat menggunakan ossutil sebagai nama biner di baris perintah, terlepas dari sistem operasi Anda. Jika Anda menggunakan versi sebelum 1.6.16, Anda harus menyesuaikan nama biner sesuai dengan sistem operasi Anda. Untuk informasi lebih lanjut, lihat Referensi Perintah ossutil.

      Izin

      Secara default, Akun Alibaba Cloud memiliki izin penuh atas sumber dayanya. Pengguna Resource Access Management (RAM) atau Peran RAM tidak memiliki izin apa pun secara default. Anda harus memberikan izin kepada Pengguna RAM atau Peran RAM menggunakan Kebijakan RAM atau Kebijakan Bucket.

      Aksi API

      Deskripsi

      oss:GetObject

      Diperlukan untuk mengunduh objek.

      oss:GetObjectVersion

      Opsional. Diperlukan untuk mengunduh versi tertentu dari objek sumber menggunakan opsi --version-id.

      kms:GenerateDataKey

      Opsional. Diperlukan jika objek yang diunduh dienkripsi di sisi server menggunakan KMS.

      kms:Decrypt

      oss:ListObjects

      Opsional. Diperlukan untuk unduhan batch (operasi rekursif).

      Sintaksis

      ossutil cp cloud_url file_url [options]

      Parameter

      Deskripsi

      cloud_url

      Jalur sumber objek OSS. Formatnya adalah oss://bucket[/prefix]. Contohnya, oss://examplebucket/examplefile.txt.

      file_url

      Jalur tujuan untuk file lokal. Jika tujuannya adalah direktori, jalur harus diakhiri dengan pemisah (/ atau \). Contohnya, jalur Linux adalah /localfolder/examplefile.txt dan jalur Windows adalah D:\localfolder\examplefile.txt.

      -r, --recursive

      Menerapkan operasi secara rekursif ke semua objek yang cocok di bawah awalan yang ditentukan. Jika tidak, operasi hanya berlaku untuk satu objek yang ditentukan.

      -f --force

      Memaksa operasi tanpa meminta konfirmasi.

      -u，--update

      Melakukan unduhan hanya jika file tujuan tidak ada atau jika waktu modifikasi terakhir objek sumber lebih baru daripada file tujuan.

      --maxdownspeed

      Kecepatan unduhan maksimum dalam KB/s. Nilai default adalah 0, yang berarti tidak ada batasan kecepatan.

      --disable-ignore-error

      Menonaktifkan pengabaian kesalahan selama operasi batch.

      --only-current-dir

      Mengunduh hanya objek di direktori saat ini dan mengabaikan subdirektori serta objek di dalamnya.

      --bigfile-threshold

      Ambang batas ukuran dalam byte untuk unduhan yang dapat dilanjutkan.

      Default: 100 MB

      Rentang nilai: 0 hingga 9223372036854775807

      --part-size

      Ukuran part dalam byte. Secara default, ossutil secara otomatis menghitung ukuran part yang sesuai berdasarkan ukuran objek.

      Rentang nilai: 1 hingga 9223372036854775807

      --checkpoint-dir

      Direktori tempat ossutil menyimpan informasi checkpoint untuk unduhan yang dapat dilanjutkan. Jika unduhan yang dapat dilanjutkan gagal, ossutil membuat direktori .ossutil_checkpoint untuk mencatat informasi checkpoint. ossutil menghapus direktori ini setelah unduhan berhasil. Pastikan direktori yang ditentukan dapat dihapus.

      --range

      Mengunduh rentang byte tertentu dari objek dan menyimpannya sebagai file baru. Penomoran byte dimulai dari nol.

      • Tentukan rentang

        Contohnya, 3-9 mengunduh byte dari byte ke-3 hingga byte ke-9, inklusif.

      • Tentukan posisi awal

        Contohnya, 3- mengunduh dari byte ke-3 hingga akhir objek, inklusif.

      • Tentukan posisi akhir

        Contohnya, -9 mengunduh dari byte ke-0 hingga byte ke-9, inklusif.

      --encoding-type

      Tipe enkode nama objek. Atur opsi ini ke url. Jika opsi ini tidak ditentukan, nama objek tidak dienkode.

      --include

      Memasukkan semua objek yang cocok dengan pola yang ditentukan.

      Untuk informasi lebih lanjut, lihat opsi include dan exclude.

      --exclude

      Mengeluarkan semua objek yang cocok dengan pola yang ditentukan.

      Untuk informasi lebih lanjut, lihat opsi include dan exclude.

      --meta

      Menetapkan metadata untuk objek. Formatnya adalah header:value#header:value. Contoh: Cache-Control:no-cache#Content-Encoding:gzip. Untuk informasi lebih lanjut tentang metadata, lihat set-meta (Kelola metadata objek).

      --acl

      Daftar kontrol akses (ACL) objek. Nilai valid:

      • default (default): Objek mewarisi ACL dari bucket.

      • private: Hanya pemilik bucket yang memiliki izin baca dan tulis. Pengguna lain tidak dapat mengakses objek di bucket.

      • public-read: Hanya pemilik bucket yang memiliki izin tulis. Semua pengguna lain, termasuk pengguna anonim, memiliki izin baca saja pada objek di bucket. Ini dapat menyebabkan kebocoran data dan biaya tambahan. Gunakan ACL ini dengan hati-hati.

      • public-read-write: Siapa pun, termasuk pengguna anonim, dapat membaca dan menulis objek di bucket. Ini dapat menyebabkan kebocoran data, biaya tambahan, dan potensi tanggung jawab hukum jika konten jahat diunggah. Kecuali untuk kasus penggunaan tertentu, jangan konfigurasikan izin baca-tulis publik.

      --snapshot-path

      Direktori tempat informasi snapshot disimpan selama unduhan. Untuk unduhan berikutnya, ossutil membaca informasi snapshot dari direktori ini untuk melakukan unduhan inkremental.

      --disable-crc64

      Menonaktifkan pemeriksaan redundansi siklik 64-bit (CRC-64). Secara default, ossutil mengaktifkan CRC-64 untuk semua transfer data.

      --payer

      Metode pembayaran untuk permintaan. Untuk membuat peminta membayar lalu lintas dan permintaan yang dihasilkan dari mengakses jalur yang ditentukan, atur opsi ini ke requester.

      --partition-download

      Menentukan partisi objek untuk diunduh. Nilainya dalam format Nomor partisi:Total partisi. Contohnya, 1:5 menunjukkan bahwa perintah ossutil ini mengunduh partisi 1 dari total 5 partisi. Nomor partisi bersifat 1-based. Algoritma internal alat ini menentukan bagaimana ossutil membagi objek. Opsi ini memungkinkan Anda membagi objek menjadi beberapa partisi dan mengunduhnya secara paralel menggunakan beberapa perintah ossutil. Setiap perintah mengunduh partisi yang ditugaskan.

      -j，--job

      Jumlah tugas konkuren untuk operasi multi-objek. Default: 3. Rentang nilai: 1 hingga 10.000.

      --parallel

      Jumlah tugas konkuren untuk operasi single-objek. Rentang nilai: 1 hingga 10.000. Jika opsi ini tidak diatur, ossutil menentukan nilainya berdasarkan jenis operasi dan ukuran objek.

      --version-id

      Mengunduh versi tertentu dari objek. Gunakan opsi --version-id hanya dengan bucket yang memiliki pengendalian versi. Untuk mengaktifkan pengendalian versi untuk bucket, lihat bucket-versioning (Pengendalian versi).

      --start-time

      Stempel waktu UNIX. Jika Anda menentukan opsi ini, objek dengan waktu modifikasi terakhir lebih awal dari stempel waktu ini akan diabaikan.

      Catatan

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

      --end-time

      Stempel waktu UNIX. Jika Anda menentukan opsi ini, objek dengan waktu modifikasi terakhir lebih baru dari stempel waktu ini akan diabaikan.

      Catatan

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

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

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

      Jika konkurensi default tidak memenuhi kebutuhan performa Anda, Anda dapat menyesuaikan opsi -j, --jobs dan --parallel untuk menyetel performa. Secara default, ossutil menghitung jumlah paralel berdasarkan ukuran objek. Saat Anda mentransfer objek besar dalam batch, konkurensi aktual adalah jumlah pekerjaan dikalikan dengan jumlah paralel.

      • Jika Instance ECS atau server yang menjalankan perintah memiliki sumber daya terbatas, seperti jaringan, memori, atau CPU, kami sarankan Anda menetapkan konkurensi ke nilai di bawah 100. Jika sumber daya ini tidak sepenuhnya digunakan, Anda dapat meningkatkan konkurensi.

      • Menetapkan konkurensi terlalu tinggi dapat menurunkan performa atau menyebabkan kesalahan EOF karena overhead pergantian thread dan persaingan sumber daya. Anda dapat menyesuaikan opsi -j, --jobs dan --parallel berdasarkan sumber daya mesin Anda. Saat melakukan uji stres, mulailah dengan nilai konkurensi rendah dan tingkatkan secara bertahap untuk menemukan pengaturan optimal.

      Contoh

      Contoh berikut ini untuk sistem Linux. Anda harus menyesuaikan parameter agar sesuai dengan sistem operasi dan lingkungan Anda. Contoh-contoh ini mengasumsikan hal berikut:

      • Nama bucket: examplebucket

      • Direktori OSS: destfolder/

      • Direktori lokal: localfolder/

      • File lokal: examplefile.txt

      Mengunduh satu objek

      • Unduh objek ke direktori yang ditentukan dan pertahankan nama aslinya:

        ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/

      • Unduh objek ke direktori yang ditentukan dan ubah namanya menjadi example.txt:

        ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt

      Unduhan batch

      • Gunakan opsi -r untuk mengunduh direktori destfolder, termasuk semua subdirektori dan objeknya.

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

      • Gunakan opsi --only-current-dir untuk mengunduh hanya objek di direktori saat ini dan abaikan subdirektori apa pun.

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

      • Gunakan opsi -u untuk mengunduh hanya objek yang tidak ada secara lokal atau telah diperbarui di OSS. Opsi ini melewati pengunduhan objek jika file lokal dengan nama dan waktu modifikasi terakhir yang sama sudah ada.

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

      Mengunduh objek bersyarat

      • Unduh semua objek yang bukan dalam format JPG dari direktori destfolder:

        ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg"

      • Unduh objek dari direktori destfolder yang mengandung abc dalam nama mereka tetapi bukan dalam format JPG atau TXT:

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

      Batasi kecepatan unduhan

      Gunakan opsi --maxdownspeed untuk membatasi kecepatan unduhan hingga 1 MB/s (1.024 KB/s).

      ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --maxdownspeed 1024

      Unduhan rentang

      Gunakan opsi --range untuk mengunduh byte 10 hingga 20 dari examplefile.txt ke komputer lokal Anda.

      ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --range 10-20

      Mengunduh objek dalam rentang waktu tertentu

      Gunakan opsi --start-time dan --end-time untuk mengunduh hanya objek di direktori destfolder yang terakhir dimodifikasi antara pukul 10:09:18 pada tanggal 31 Oktober 2023 (UTC+8) dan pukul 12:55:58 pada tanggal 31 Oktober 2023 (UTC+8).

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

      Mengunduh versi tertentu dari objek

      Pertama, gunakan perintah ls --all-versions untuk mendapatkan semua ID versi objek. Kemudian, gunakan opsi --version-id untuk mengunduh versi tertentu.

      Catatan

      Opsi --version-id hanya dapat digunakan untuk objek di bucket yang memiliki pengendalian versi. Untuk mengaktifkan pengendalian versi untuk bucket, lihat bucket-versioning (Pengendalian Versi).

      ossutil cp oss://examplebucket/test.jpg localfolder/ --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

      Mengunduh objek dan menghasilkan informasi snapshot

      Gunakan opsi --snapshot-path untuk menghasilkan informasi snapshot untuk objek yang diunduh di direktori tertentu. Saat Anda menjalankan perintah unduhan berikutnya dengan opsi ini, ossutil membaca informasi snapshot dari direktori tersebut untuk melakukan unduhan inkremental. Untuk informasi lebih lanjut, lihat Unggah Objek dan Hasilkan Snapshot.

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

      Unduhan lintas akun atau lintas wilayah

      Gunakan opsi umum -e, -i, dan -k untuk mengunduh objek dari bucket yang dimiliki oleh akun lain dan berlokasi di wilayah China (Shanghai).

      Catatan

      Tentukan Endpoint yang sesuai dengan wilayah tempat bucket berada. Untuk informasi lebih lanjut, lihat Wilayah dan Endpoint.

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