Letakkan Rentang
Operasi Put Range menulis rentang byte ke file.
Ketersediaan protokol
| Mengaktifkan protokol berbagi file | Tersedia |
|---|---|
| SMB |  |
| NFS |  |
Minta
Permintaan Put Range dapat dibuat sebagai berikut. Kami menyarankan agar Anda menggunakan HTTPS.
| Metode | Meminta URI | Versi HTTP |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
Ganti komponen jalur yang ditunjukkan dalam URI permintaan dengan milik Anda sendiri, sebagai berikut:
| Komponen jalur | Deskripsi |
|---|---|
myaccount |
Nama akun penyimpanan Anda. |
myshare |
Nama berbagi file Anda. |
mydirectorypath |
Pilihan. Jalur ke direktori induk. |
myfile |
Nama file. |
Untuk informasi tentang pembatasan penamaan jalur, lihat Berbagi nama dan referensi, direktori, file, dan metadata.
Parameter URI
Parameter tambahan berikut dapat ditentukan pada URI permintaan.
| Parameter | Deskripsi |
|---|---|
timeout |
Opsional. Parameter timeout dinyatakan dalam hitung detik. Untuk informasi selengkapnya, lihat Mengatur waktu habis untuk operasi layanan File. |
Header permintaan
Header permintaan yang diperlukan dan opsional dijelaskan dalam tabel berikut:
| 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. Untuk informasi selengkapnya, lihat Penerapan versi untuk layanan Azure Storage. |
Range atau x-ms-range |
Baik Range atau x-ms-range diperlukan.Menentukan rentang byte yang akan ditulis. Mulai dan akhir rentang harus ditentukan. Header ini ditentukan oleh spesifikasi protokol HTTP/1.1. Untuk operasi pembaruan, rentangnya bisa berukuran hingga 4 MiB. Untuk operasi yang jelas, rentang dapat mencapai nilai ukuran penuh file. Layanan File hanya menerima satu rentang byte untuk Range header dan x-ms-range , dan rentang byte harus ditentukan dalam format berikut: bytes=startByte-endByte.Jika dan Rangex-ms-range ditentukan, layanan menggunakan nilai x-ms-range. Untuk informasi selengkapnya, lihat Menentukan header rentang untuk operasi layanan File. |
Content-Length |
Wajib diisi. Menentukan jumlah byte yang dikirimkan dalam isi permintaan. x-ms-write Ketika header diatur ke clear, nilai header ini harus diatur ke 0. |
Content-MD5 |
Opsional. Hash MD5 dari konten. Hash ini digunakan untuk memverifikasi integritas data selama transportasi. Content-MD5 Saat header ditentukan, Azure Files membandingkan hash konten yang telah tiba dengan nilai header yang dikirim. Jika dua hash tidak cocok, operasi gagal dengan kode kesalahan 400 (Permintaan Buruk).Header Content-MD5 tidak diizinkan saat x-ms-write header diatur ke clear. Jika disertakan dengan permintaan, layanan File mengembalikan kode status 400 (Permintaan Buruk). |
x-ms-write: { update ¦ clear } |
Wajib diisi. Anda harus menentukan salah satu opsi berikut:
|
x-ms-lease-id: <ID> |
Diperlukan jika file memiliki sewa aktif. Tersedia untuk versi 2019-02-02 dan yang lebih baru. |
x-ms-client-request-id |
Opsional. Menyediakan nilai buram yang dihasilkan klien dengan batas karakter 1 kibibyte (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 Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Pilihan. Versi 2021-06-08 dan yang lebih baru. Anda dapat menentukan salah satu opsi berikut:
|
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 di url permintaan harus dipangkas atau tidak. Untuk informasi selengkapnya, lihat Penamaan dan referensi berbagi, direktori, file, dan metadata. |
Isi permintaan
Data yang mewakili rentang yang akan diunggah.
Permintaan sampel: Perbarui rentang byte
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Permintaan sampel: Hapus rentang byte
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Respons
Respons mencakup kode status HTTP dan sekumpulan header respons.
Kode status
Operasi yang berhasil mengembalikan kode status 201 (Dibuat).
Untuk informasi selengkapnya tentang kode status, lihat Kode status dan kesalahan.
Header respons
Respons untuk operasi ini mencakup header berikut. Respons juga dapat mencakup header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1.
| Header respons | Deskripsi |
|---|---|
ETag |
ETag berisi nilai yang mewakili versi file. Nilai diapit dalam tanda kutip. |
Last-Modified |
Mengembalikan tanggal dan waktu direktori terakhir diubah. Format tanggal mengikuti RFC 1123. Untuk informasi selengkapnya, lihat Mewakili nilai tanggal/waktu di header. Setiap operasi yang memodifikasi berbagi atau properti atau metadatanya memperbarui waktu modifikasi terakhir. Operasi pada file tidak memengaruhi waktu terakhir pembagian yang dimodifikasi. |
Content-MD5 |
Header ini dikembalikan sehingga klien dapat memeriksa integritas konten pesan. Nilai header ini dihitung oleh layanan File. Ini tidak selalu sama dengan nilai yang ditentukan dalam header permintaan. |
x-ms-request-id |
Secara unik mengidentifikasi permintaan yang dibuat, dan dapat digunakan untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat Memecahkan masalah operasi API. |
x-ms-version |
Menunjukkan versi layanan File yang digunakan untuk menjalankan permintaan. |
Date |
Nilai tanggal/waktu UTC yang dihasilkan oleh layanan, yang menunjukkan waktu saat respons dimulai. |
x-ms-request-server-encrypted: { true ¦ false } |
Versi 2017-04-17 dan yang lebih baru. Nilai header ini diatur ke true jika konten permintaan berhasil dienkripsi dengan menggunakan algoritma yang ditentukan. Jika tidak, nilai diatur ke false. |
x-ms-client-request-id |
Header ini 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 berisi tidak lebih dari 1.024 karakter ASCII yang terlihat. x-ms-client-request-id Jika header tidak ada dalam permintaan, header tidak ada dalam respons. |
x-ms-file-last-write-time |
Versi 2021-06-08 dan yang lebih baru. Waktu tulis terakhir untuk file, dalam format ISO 8601. Contoh: 2017-05-10T17:52:33.9551861Z. |
Isi Respons
Tidak ada.
Respons sampel
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Authorization
Hanya pemilik akun yang dapat memanggil operasi ini.
Keterangan
Operasi Put Range menulis rentang byte ke file. Operasi ini hanya dapat dipanggil pada file yang ada. Ini tidak dapat dipanggil untuk membuat file baru. Memanggil Put Range dengan nama file yang saat ini tidak ada mengembalikan kode status 404 (Tidak Ditemukan).
Untuk membuat file baru, panggil Buat File. File dapat berukuran hingga 4 TiB.
Put Range Operasi diizinkan 10 menit per MiB untuk diselesaikan. Jika operasi membutuhkan waktu rata-rata lebih dari 10 menit per MiB, waktunya habis.
Jika file memiliki sewa aktif, klien harus menentukan ID sewa yang valid pada permintaan untuk menulis rentang.
Operasi pembaruan rentang
Memanggil Put Range dengan Update opsi melakukan penulisan di tempat pada file yang ditentukan. Konten apa pun dalam rentang yang ditentukan ditimpa dengan pembaruan. Setiap rentang yang dikirimkan dengan Put Range untuk operasi pembaruan mungkin berukuran hingga 4 MiB. Jika Anda mencoba mengunggah rentang yang lebih besar dari 4 MiB, layanan mengembalikan kode status 413 (Entitas Permintaan Terlalu Besar).
Operasi rentang yang jelas
Put Range Panggilan dengan Clear opsi melepaskan ruang dalam penyimpanan selama rentang yang ditentukan selaras dengan 512 byte. Rentang yang telah dibersihkan tidak lagi dilacak sebagai bagian dari file dan tidak dikembalikan dalam respons Rentang Daftar . Jika rentang yang ditentukan tidak selaras 512 byte, operasi menulis nol ke awal atau akhir rentang yang tidak selaras 512 byte dan membebaskan sisa rentang di dalamnya yang selaras 512 byte.
Rentang apa pun yang belum dibersihkan dikembalikan dalam respons Rentang Daftar . Misalnya, lihat bagian "Sampel rentang jelas yang tidak ditandatangani" yang mengikuti.
Sewa file
Anda dapat memanggil File Sewa untuk mendapatkan kunci tulis eksklusif ke file terhadap tulisan lain selama durasi tak terbatas.
Kunci rentang byte klien SMB
Protokol SMB memungkinkan kunci rentang byte untuk mengelola akses baca dan tulis ke wilayah file. Ini berarti bahwa Put Range gagal jika klien SMB memiliki kunci yang tumpang tindih dengan rentang yang ditentukan oleh Put Range operasi menggunakan x-ms-range. Untuk informasi selengkapnya, lihat Mengelola kunci file.
Pemberitahuan perubahan direktori klien SMB
Protokol SMB mendukung fungsi FindFirstChangeNotification API yang memungkinkan aplikasi mendeteksi kapan perubahan terjadi dalam sistem file. Ini dapat mendeteksi kapan file atau direktori ditambahkan, diubah, atau dihapus, dan kapan ukuran, atribut, atau deskriptor keamanan file berubah. Klien SMB yang menggunakan API ini tidak akan menerima pemberitahuan saat perubahan file atau direktori terjadi melalui Azure Files REST API. Namun, perubahan yang disebabkan oleh klien SMB lainnya menyebarluaskan pemberitahuan.
Sampel rentang kosong yang tidak ditandatangani
Misalkan file dibuat dengan Buat File dan satu rentang ditulis dengan Put Range, sebagai berikut:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Melakukan operasi Rentang Daftar pada file mengembalikan isi respons berikut:
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Sekarang misalkan bahwa operasi rentang byte rentang jelas yang tidak ditandatangani dilakukan:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Operasi Rentang Daftar berikutnya pada file mengembalikan isi respons berikut:
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
Perhatikan bahwa nol telah ditulis ke ruang yang tidak sejajar dari 768-1024 dan 2048-2304.
Put Range tidak didukung pada salinan bayangan berbagi, yang merupakan salinan berbagi baca-saja. Upaya untuk melakukan operasi ini pada salinan bayangan berbagi gagal dengan 400 (InvalidQueryParameterValue).