Letakkan Rentang

Artikel
03/29/2023

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: `update`: Menulis byte yang ditentukan oleh isi permintaan ke dalam rentang yang ditentukan. Header `Range` dan `Content-Length` harus cocok untuk melakukan pembaruan. `clear`: Menghapus rentang yang ditentukan dan melepaskan ruang yang digunakan dalam penyimpanan untuk rentang tersebut. Untuk menghapus rentang, atur `Content-Length` header ke `0`, dan atur `Range` header ke nilai yang menunjukkan rentang untuk menghapus, hingga ukuran file maksimum.
`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: `now`: Nilai default. Updates tanda waktu tulis terakhir ke waktu permintaan. `preserve`: Menjaga tanda waktu tulis terakhir yang ada tidak berubah.
`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).

Lihat juga

Operasi pada File

Bagikan melalui