Salin File

Artikel
03/29/2023

Operasi Copy File menyalin blob atau file ke file tujuan dalam akun penyimpanan.

Tersedia dalam versi 2015-02-21 dan yang lebih baru.

Ketersediaan protokol

Mengaktifkan protokol berbagi file	Tersedia
SMB
NFS

Minta

Anda dapat membuat Copy File permintaan sebagai berikut. Kami merekomendasikan HTTPS.

Dimulai dengan versi 2013-08-15, Anda dapat menentukan tanda tangan akses bersama untuk file tujuan jika berada di akun yang sama dengan file sumber. Dimulai dengan versi 2015-04-05, Anda juga dapat menentukan tanda tangan akses bersama untuk file tujuan jika berada di akun penyimpanan yang berbeda.

Metode	Meminta URI	Versi HTTP
`PUT`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile`	HTTP/1.1

Ganti komponen jalur yang ditunjukkan dalam permintaan URI dengan milik Anda sendiri, sebagai berikut:

Komponen jalur	Deskripsi
`myaccount`	Nama akun penyimpanan Anda.
`myshare`	Nama berbagi file Anda.
`mydirectorypath`	Opsional. Jalur ke direktori induk.
`myfile`	Nama file.

Untuk detail tentang pembatasan penamaan jalur, lihat Menamai dan mereferensikan berbagi, direktori, file, dan metadata.

Parameter URI

Anda dapat menentukan parameter tambahan berikut pada permintaan URI:

Parameter	Deskripsi
`timeout`	Opsional. Parameter batas waktu dinyatakan dalam detik. Untuk informasi selengkapnya, lihat Mengatur batas waktu untuk operasi Azure Files.

Header permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional:

Meminta kop	Deskripsi
`Authorization`	Wajib diisi. Menentukan skema otorisasi, nama akun, dan tanda tangan. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage.
`Date` atau `x-ms-date`	Wajib diisi. Menentukan Waktu Universal Terkoordinasi (UTC) untuk permintaan tersebut. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage.
`x-ms-version`	Diperlukan untuk semua permintaan yang diotorisasi. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Operasi ini hanya tersedia dalam versi 2015-02-21 dan yang lebih baru. Untuk informasi selengkapnya, lihat Penerapan versi untuk layanan Azure Storage.
`x-ms-meta-name:value`	Opsional. Menentukan pasangan nama/nilai yang terkait dengan file sebagai metadata. Jika tidak ada pasangan nama/nilai yang ditentukan, operasi menyalin metadata dari blob sumber atau file ke file tujuan. Jika satu atau beberapa pasangan nama/nilai ditentukan, file tujuan dibuat dengan metadata yang ditentukan, dan metadata tidak disalin dari blob sumber atau file. Nama metadata harus mematuhi aturan penamaan untuk pengidentifikasi C#. Perhatikan bahwa metadata file yang ditentukan melalui Azure Files tidak dapat diakses dari klien SMB.
`x-ms-copy-source:name`	Wajib diisi. Menentukan URL file sumber atau blob, panjangnya hingga 2 kibibyte (KiB). Untuk menyalin file ke file lain dalam akun penyimpanan yang sama, Anda dapat menggunakan kunci bersama untuk mengotorisasi file sumber. Jika Anda menyalin file dari akun penyimpanan lain, atau jika Anda menyalin blob dari akun penyimpanan yang sama atau akun penyimpanan lain, Anda harus mengotorisasi file sumber atau blob dengan menggunakan tanda tangan akses bersama. Jika sumbernya adalah blob publik, tidak ada otorisasi yang diperlukan untuk melakukan operasi salin. Anda juga dapat menentukan file dalam salinan bayangan berbagi sebagai sumber salinan. Berikut adalah beberapa contoh URL objek sumber: `https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile` `https://myaccount.blob.core.windows.net/mycontainer/myblob?sastoken` `http://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>`
`x-ms-lease-id:<ID>`	Diperlukan jika file tujuan memiliki sewa aktif. Tersedia untuk versi 2019-02-02 dan yang lebih baru. ID sewa yang ditentukan untuk header ini harus cocok dengan ID sewa file tujuan. Jika permintaan tidak menyertakan ID sewa atau ID tidak valid, operasi gagal dengan kode status 412 (Prasyarat Gagal). Jika header ini ditentukan dan file tujuan saat ini tidak memiliki sewa aktif, operasi gagal dengan kode status 412 (Prasyarat Gagal).
`x-ms-file-permission-copy-mode: { source ¦ override }`	Opsional. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Menentukan perilaku penyalinan pendeskripsi keamanan file: `source`: Deskriptor keamanan pada file tujuan disalin dari file sumber. `override`: Deskriptor keamanan pada file tujuan ditentukan melalui `x-ms-file-permission` header atau `x-ms-file-permission-key` .
`x-ms-file-permission`	Diperlukan jika `x-ms-file-permission-copy-mode` ditentukan sebagai `override` dan `x-ms-file-permission-key` tidak ditentukan. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Izin ini adalah deskriptor keamanan untuk file yang ditentukan dalam Bahasa Definisi Deskriptor Keamanan (SDDL). Anda dapat menggunakan header ini jika ukuran izin adalah 8 kibibyte (KiB) atau kurang. Jika tidak, Anda dapat menggunakan `x-ms-file-permission-key`. Jika ditentukan, harus memiliki pemilik, grup, dan daftar kontrol akses diskresi (DACL). Perhatikan bahwa hanya salah satu dari `x-ms-file-permission` atau `x-ms-file-permission-key` yang dapat ditentukan.
`x-ms-file-permission-key`	Diperlukan jika `x-ms-file-permission-copy-mode` ditentukan sebagai `override` dan `x-ms-file-permission` tidak ditentukan. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Header ini menentukan kunci izin yang akan diatur untuk file. Anda dapat membuat kunci ini dengan menggunakan `Create Permission` operasi . Perhatikan bahwa hanya salah satu dari `x-ms-file-permission` atau `x-ms-file-permission-key` yang dapat ditentukan.
`x-ms-file-copy-ignore-readonly`	Pilihan. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Nilai Boolean ini menentukan apakah `ReadOnly` atribut pada file tujuan yang sudah ada sebelumnya harus dihormati. Jika , `true`operasi salin berhasil. Jika tidak, file sebelumnya di tujuan dengan `ReadOnly` set atribut menyebabkan operasi salin gagal.
`x-ms-file-attributes`	Pilihan. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Header ini menentukan atribut sistem file yang akan diatur pada file tujuan. Lihat daftar atribut yang tersedia. Anda dapat menggunakan nilai `source` untuk menyalin atribut dari file sumber ke file tujuan. Anda dapat menggunakan nilai `none` untuk menghapus semua atribut pada file tujuan.
`x-ms-file-creation-time`	Pilihan. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Header ini menentukan properti untuk waktu pembuatan, dalam UTC, untuk diatur pada file tujuan. Anda dapat menggunakan nilai `source` untuk menyalin waktu pembuatan dari file sumber ke file tujuan.
`x-ms-file-last-write-time`	Pilihan. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Header ini menentukan properti untuk waktu tulis terakhir, dalam UTC, untuk diatur pada file tujuan. Anda dapat menggunakan nilai `source` untuk menyalin waktu tulis terakhir dari file sumber ke file tujuan.
`x-ms-file-copy-set-archive`	Pilihan. Tersedia untuk versi 2019-07-07 dan yang lebih baru. Nilai Boolean ini menentukan apakah `Archive` atribut harus diatur, terlepas dari `x-ms-file-attributes` nilai header.
`x-ms-client-request-id`	Pilihan. Menyediakan nilai buram yang dihasilkan klien dengan batas karakter 1 KiB yang dicatat dalam log saat pengelogan dikonfigurasi. Kami sangat menyarankan Anda menggunakan header ini untuk menghubungkan aktivitas sisi klien dengan permintaan yang diterima server. Untuk informasi selengkapnya, lihat Memantau Azure Blob Storage.
`x-ms-file-change-time: { <DateTime> ¦ source }`	Pilihan. Versi 2021-06-08 dan yang lebih baru. Properti waktu perubahan UTC untuk file, diformat dalam format ISO 8601. Nilai `source` dapat digunakan untuk menyalin waktu perubahan dari file sumber ke file tujuan. Stempel waktu default adalah waktu permintaan.
`x-ms-file-request-intent`	Diperlukan jika `Authorization` header menentukan token OAuth. Nilai yang dapat diterima adalah `backup`. Header ini menentukan bahwa `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` atau `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` harus diberikan jika disertakan dalam kebijakan RBAC yang ditetapkan ke identitas yang diotorisasi menggunakan `Authorization` header . Tersedia untuk versi 2022-11-02 dan yang lebih baru.
`x-ms-allow-trailing-dot: { <Boolean> }`	Pilihan. Versi 2022-11-02 dan yang lebih baru. Nilai Boolean menentukan apakah titik berikutnya yang ada dalam url permintaan harus dipangkas atau tidak. Untuk informasi selengkapnya, lihat Memberi nama dan mereferensikan berbagi, direktori, file, dan metadata.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Pilihan. Versi 2022-11-02 dan yang lebih baru. Nilai Boolean menentukan apakah titik berikutnya yang ada di url sumber harus dipangkas atau tidak. Header ini harus ditentukan hanya jika sumber salin adalah File Azure. Header ini tidak didukung untuk jenis sumber salinan lainnya. Untuk informasi selengkapnya, lihat Memberi nama dan mereferensikan berbagi, direktori, file, dan metadata.

Isi permintaan

Tidak ada.

Respons

Respons mencakup kode status HTTP dan sekumpulan header respons.

Kode status

Operasi yang berhasil mengembalikan kode status 202 (Diterima).

Untuk informasi tentang kode status, lihat Status dan kode kesalahan.

Header respons

Respons untuk operasi ini mencakup header berikut. Respons juga mencakup header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1.

Header respons	Deskripsi
`ETag`	Jika operasi salin selesai, berisi `ETag` nilai file tujuan. Jika operasi salin tidak selesai, berisi `ETag` nilai file kosong yang dibuat di awal operasi.
`Last-Modified`	Mengembalikan tanggal/waktu operasi salin ke file tujuan selesai.
`x-ms-request-id`	Secara unik mengidentifikasi permintaan yang dibuat. Anda dapat menggunakan header ini untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat Memecahkan masalah operasi API.
`x-ms-version`	Menunjukkan versi Azure Files yang digunakan untuk menjalankan permintaan.
`Date`	Nilai tanggal/waktu UTC yang menunjukkan waktu di mana layanan mengirim respons.
`x-ms-copy-id: <id>`	Menyediakan pengidentifikasi string untuk operasi penyalinan ini. Gunakan dengan `Get File` atau `Get File Properties` untuk memeriksa status operasi salin ini, atau teruskan ke `Abort Copy File` untuk membatalkan operasi penyalinan yang tertunda.
`x-ms-copy-status: <success ¦ pending>`	Menunjukkan status operasi salin dengan nilai-nilai ini: - `success`: Operasi salin berhasil diselesaikan. - `pending`: Operasi salin masih berlangsung.
`x-ms-client-request-id`	Dapat digunakan untuk memecahkan masalah permintaan dan respons yang sesuai. Nilai header ini sama dengan nilai `x-ms-client-request-id` header jika ada dalam permintaan dan nilainya paling banyak 1.024 karakter ASCII yang terlihat. `x-ms-client-request-id` Jika header tidak ada dalam permintaan, header ini tidak akan ada dalam respons.

Isi Respons

Tidak ada

Respons sampel

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2015-02-21  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: pending  
Date: <date>

Authorization

Operasi ini dapat dipanggil oleh pemilik akun, atau oleh klien yang memiliki tanda tangan akses bersama yang memiliki izin untuk menulis ke file tujuan atau berbaginya. Perhatikan bahwa tanda tangan akses bersama yang ditentukan pada permintaan hanya berlaku untuk file tujuan.

Akses ke file sumber atau blob diotorisasi secara terpisah, seperti yang dijelaskan dalam detail untuk header x-ms-copy-sourcepermintaan .

Tabel berikut ini menjelaskan bagaimana tujuan dan objek sumber untuk Copy File operasi dapat diotorisasi:

File	Otorisasi dengan Kunci Bersama atau Kunci Bersama Lite	Otorisasi dengan tanda tangan akses bersama	Objek publik tidak memerlukan otorisasi
File tujuan	Ya	Ya	Tidak berlaku
File sumber dalam akun yang sama	Ya	Ya	Tidak berlaku
File sumber di akun lain	Tidak	Ya	Tidak berlaku
Blob sumber di akun yang sama atau akun lain	Tidak	Ya	Ya

Atribut sistem file

Atribut	Atribut file Win32	Definisi
`ReadOnly`	`FILE_ATTRIBUTE_READONLY`	File bersifat baca-saja. Aplikasi dapat membaca file tetapi tidak dapat menulis atau menghapusnya.
`Hidden`	`FILE_ATTRIBUTE_HIDDEN`	File disembunyikan. Ini tidak termasuk dalam daftar direktori biasa.
`System`	`FILE_ATTRIBUTE_SYSTEM`	Sistem operasi menggunakan bagian dari file , atau menggunakan file secara eksklusif.
`None`	`FILE_ATTRIBUTE_NORMAL`	File tidak memiliki atribut lain yang ditetapkan. Atribut ini hanya valid saat digunakan sendiri.
`Archive`	`FILE_ATTRIBUTE_ARCHIVE`	File adalah file arsip. Aplikasi biasanya menggunakan atribut ini untuk menandai file untuk pencadangan atau penghapusan.
`Temporary`	`FILE_ATTRIBUTE_TEMPORARY`	File sedang digunakan untuk penyimpanan sementara.
`Offline`	`FILE_ATTRIBUTE_OFFLINE`	Data file tidak segera tersedia. Atribut sistem file ini terutama menyediakan kompatibilitas dengan Windows. Azure Files tidak mendukungnya dengan opsi penyimpanan offline.
`NotContentIndexed`	`FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`	Layanan pengindeksan konten tidak akan mengindeks file.
`NoScrubData`	`FILE_ATTRIBUTE_NO_SCRUB_DATA`	Pemindai integritas data latar belakang tidak akan membaca aliran data pengguna. Atribut sistem file ini terutama menyediakan kompatibilitas dengan Windows.

Keterangan

Operasi Copy File dapat selesai secara asinkron. Anda dapat menggunakan ID salin yang x-ms-copy-id dikembalikan header respons untuk memeriksa status operasi salin atau untuk membatalkannya. Azure Files menyalin file berdasarkan upaya terbaik.

Jika ada file tujuan, file tersebut akan ditimpa. Anda tidak dapat mengubah file tujuan saat operasi salin sedang berlangsung.

Operasi Copy File selalu menyalin seluruh blob atau file sumber. Menyalin rentang byte atau sekumpulan blok tidak didukung.

Sumber Copy File operasi dapat menjadi file yang berada dalam salinan bayangan berbagi. Tujuan Copy File operasi tidak boleh berupa file yang berada dalam salinan bayangan berbagi.

Ketika sumber operasi salin menyediakan ETag nilai, jika ada perubahan pada sumber saat operasi sedang berlangsung, operasi akan gagal. Upaya untuk mengubah file tujuan saat operasi penyalinan sedang berlangsung akan gagal dengan kode status 409 (Konflik).

Nilai ETag untuk file tujuan berubah saat Copy File operasi dimulai. Ini terus sering berubah selama operasi salin.

Menyalin properti dan metadata

Saat blob atau file disalin, properti sistem berikut disalin ke file tujuan dengan nilai yang sama:

Content-Type
Content-Encoding
Content-Language
Content-Length
Cache-Control
Content-MD5
Content-Disposition

File tujuan selalu berukuran sama dengan blob sumber atau file. Nilai Content-Length header untuk file tujuan cocok dengan nilai header tersebut untuk blob sumber atau file.

Menyalin blob atau file sewaan ke file

Operasi Copy File hanya membaca dari blob atau file sumber, sehingga sewa pada objek sumber tidak memengaruhi operasi. Operasi Copy File menyimpan ETag nilai blob sumber atau file saat operasi dimulai. ETag Jika nilai berubah sebelum operasi penyalinan selesai, operasi gagal. Anda dapat mencegah perubahan pada blob sumber file dengan menyewanya selama operasi salin.

Jika file tujuan memiliki sewa tak terbatas aktif, Anda harus menentukan ID sewanya dalam panggilan ke Copy File operasi. Saat operasi salin tertunda, operasi sewa apa pun pada file tujuan gagal dengan kode status 409 (Konflik). Sewa tak terbatas pada file tujuan dikunci dengan cara ini selama operasi salin, apakah Anda menyalin ke file tujuan yang memiliki nama yang berbeda dari sumber atau menyalin ke file tujuan dengan nama yang sama dengan sumbernya. Jika klien menentukan ID sewa pada file yang belum ada, Azure Files mengembalikan kode status 412 (Prasyarat Gagal).

Bekerja dengan operasi penyalinan yang tertunda

Operasi Copy File mungkin selesai menyalin file secara asinkron. Gunakan tabel berikut untuk menentukan langkah berikutnya berdasarkan kode status yang Copy File mengembalikan:

Kode status	Makna
202 (Diterima), x-ms-copy-status: berhasil	Operasi salin berhasil diselesaikan.
202 (Diterima), x-ms-copy-status: tertunda	Operasi salin belum selesai. Polling blob tujuan dengan menggunakan `Get File Properties` untuk memeriksa `x-ms-copy-status` hingga operasi penyalinan selesai atau gagal.
4xx, 500, atau 503	Operasi salin gagal.

Selama dan setelah Copy File operasi, properti file tujuan berisi ID Copy File salinan operasi dan URL blob sumber atau file. Ketika operasi selesai, Azure Files menulis nilai waktu dan hasil (success, , failedatau aborted) ke properti file tujuan. Jika operasi memiliki failed hasil, x-ms-copy-status-description header berisi string detail kesalahan.

Operasi yang tertunda Copy File memiliki batas waktu dua minggu. Upaya salin yang belum selesai setelah dua minggu kehabisan waktu dan meninggalkan file kosong dengan x-ms-copy-status bidang diatur ke failed dan x-ms-status-description bidang diatur ke 500 (OperationCancelled). Kesalahan non-fatal terputus-terputus yang dapat terjadi selama operasi salin mungkin menghambat kemajuan operasi tetapi tidak menyebabkannya gagal. Dalam kasus ini, x-ms-copy-status-description menjelaskan kesalahan terputus-terputus.

Setiap upaya untuk mengubah file tujuan selama operasi salin akan gagal dengan kode status 409 (Konflik), "Salin File sedang Berlangsung."

Jika Anda memanggil Abort Copy File operasi, Anda akan melihat x-ms-copy-status:aborted header. File tujuan akan memiliki metadata utuh dan panjang file 0 byte. Anda dapat mengulangi panggilan asli untuk Copy File mencoba operasi lagi.

Billing

Akun tujuan operasi Copy File dibebankan untuk satu transaksi untuk memulai operasi. Akun tujuan juga menimbulkan satu transaksi untuk setiap permintaan untuk membatalkan atau meminta status operasi salin.

Ketika file sumber atau blob berada di akun lain, akun sumber dikenakan biaya transaksi. Selain itu, jika akun sumber dan tujuan berada di wilayah yang berbeda (misalnya, AS Utara dan AS Selatan), bandwidth yang Anda gunakan untuk mentransfer permintaan dibebankan ke akun sumber sebagai keluar. Keluar antar akun dalam wilayah yang sama gratis.