File Sewa

Operasi ini Lease File membuat dan mengelola kunci pada file untuk operasi tulis dan hapus. Lease File didukung untuk versi 2019-02-02 dan yang lebih baru.

Anda dapat memanggil Lease File operasi dalam salah satu mode berikut:

• Acquire, untuk meminta sewa baru.
• Change, untuk mengubah ID sewa yang ada.
• Release, untuk membebaskan sewa jika tidak lagi diperlukan, sehingga klien lain dapat segera memperoleh sewa terhadap file.
• Break, untuk mengakhiri sewa secara paksa, tetapi pastikan bahwa klien lain tidak dapat memperoleh sewa baru sampai periode sewa saat ini telah kedaluwarsa.

Ketersediaan protokol

Mengaktifkan protokol berbagi file	Tersedia
SMB
NFS

Minta

Anda dapat membuat Lease File permintaan sebagai berikut. HTTPS disarankan.

Metode	Meminta URI	Versi HTTP
Put	https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease	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.
myfile	Nama file.

Parameter URI

Anda dapat menentukan parameter tambahan berikut pada URI permintaan.

Parameter	Deskripsi
timeout	Opsional. Parameter timeout dinyatakan dalam hitung 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	Pilihan. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Untuk informasi selengkapnya, lihat Penerapan versi untuk layanan Azure Storage.
x-ms-lease-id: <ID>	Diperlukan untuk memperbarui, mengubah, atau melepaskan sewa. Anda dapat menentukan nilai x-ms-lease-id dalam format string GUID yang valid. Lihat Konstruktor Guid (String) untuk daftar format yang valid.
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break>	acquire: Meminta sewa baru. Jika file tidak memiliki sewa aktif, Azure Files membuat sewa pada file, dan mengembalikan ID sewa baru. Jika file memiliki sewa aktif, Anda hanya dapat meminta sewa baru dengan menggunakan ID sewa aktif. change: Mengubah ID sewa sewa aktif. change harus menyertakan ID sewa saat ini di x-ms-lease-id, dan ID sewa baru di x-ms-proposed-lease-id. release: Merilis sewa. Anda dapat merilis sewa jika ID sewa yang ditentukan pada permintaan cocok dengan yang terkait dengan file. Melepaskan sewa memungkinkan klien lain untuk segera memperoleh sewa untuk file, segera setelah rilis selesai. break: Memutus sewa, jika file memiliki sewa aktif. Setiap permintaan yang diotorisasi dapat melanggar sewa. Permintaan tidak diperlukan untuk menentukan ID sewa yang cocok. Sewa tak terbatas segera rusak.
x-ms-lease-duration: -1	Diizinkan dan hanya diperlukan pada acquire operasi. Diperlukan untuk menjadi -1, untuk menunjukkan sewa yang tidak pernah kedaluwarsa.
x-ms-proposed-lease-id: <ID>	Opsional untuk acquire, dan diperlukan untuk change. ID sewa yang diusulkan, dalam format string GUID. Azure Files mengembalikan 400 (Invalid request) jika ID sewa yang diusulkan tidak dalam format yang benar. Lihat Konstruktor Guid (String) untuk daftar format yang valid.
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-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.

Isi permintaan

Tidak ada.

Permintaan sampel

Contoh permintaan berikut menunjukkan cara memperoleh sewa:

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2019-07-07  
x-ms-lease-action: acquire  
x-ms-lease-duration: -1  
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-date: <date>  
Authorization: SharedKey testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=  

Respons

Respons mencakup kode status HTTP dan sekumpulan header respons.

Kode status

Kode status keberhasilan yang dikembalikan untuk operasi sewa adalah sebagai berikut:

• Acquire: Operasi yang berhasil mengembalikan kode status 201 (Dibuat).
• Change: Operasi yang berhasil mengembalikan kode status 200 (OK).
• Release: Operasi yang berhasil mengembalikan kode status 200 (OK).
• Break: 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 dapat mencakup header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1.

Sintaks	Deskripsi
ETag	Berisi nilai yang dapat Anda gunakan untuk melakukan operasi secara kondisional, dalam tanda kutip. Operasi Lease File tidak mengubah properti ini.
Last-Modified	Tanggal/waktu file terakhir diubah. Untuk informasi selengkapnya, lihat Representasi nilai tanggal-waktu di header. Setiap operasi tulis pada file, termasuk pembaruan pada metadata atau properti file, mengubah waktu terakhir dimodifikasi file. Operasi Lease File tidak mengubah properti ini.
x-ms-lease-id: <id>	Saat Anda meminta sewa, Azure Files mengembalikan ID sewa unik. Saat sewa aktif, Anda harus menyertakan ID sewa dengan permintaan apa pun untuk menulis ke file, atau untuk mengubah, atau melepaskan sewa. Operasi perpanjangan yang berhasil juga mengembalikan ID sewa untuk sewa aktif.
x-ms-lease-time: seconds	Dikembalikan hanya untuk permintaan yang berhasil untuk memutus sewa. 0 dikembalikan untuk jeda segera.
x-ms-request-id	Secara unik mengidentifikasi permintaan yang dibuat, dan dapat digunakan untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat Pemecahan 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 respons dimulai. Layanan menghasilkan nilai ini.
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. Nilainya paling banyak 1.024 karakter ASCII yang terlihat. x-ms-client-request-id Jika header tidak ada dalam permintaan, header tidak akan ada dalam respons.

Isi Respons

Tidak ada.

Respons sampel

Berikut ini adalah respons sampel untuk permintaan untuk memperoleh sewa:

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2019-07-07
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: <date>  

Authorization

Pemilik akun dapat memanggil operasi ini. Selain itu, setiap klien dengan tanda tangan akses bersama yang memiliki izin untuk menulis ke file ini atau berbaginya dapat melakukannya.

Keterangan

Sewa pada file menyediakan akses tulis dan hapus eksklusif ke file. Untuk menulis ke file dengan sewa aktif, klien harus menyertakan ID sewa aktif dengan permintaan tulis. Sewa diberikan untuk durasi tak terbatas.

Ketika klien memperoleh sewa, ID sewa dikembalikan. Azure Files menghasilkan ID sewa jika tidak ditentukan dalam permintaan peroleh. Klien dapat menggunakan ID sewa ini untuk mengubah ID sewanya atau melepaskan sewa.

Ketika sewa aktif, ID sewa harus disertakan dalam permintaan untuk salah satu operasi berikut:

• Buat File
• Atur Metadata File
• Atur Properti File
• Hapus File
• Letakkan Rentang
• Salin File (ID Sewa diperlukan untuk file tujuan.)

Jika ID sewa tidak disertakan, operasi ini gagal pada file sewaan, dengan 412 – Precondition failed.

Operasi berikut berhasil pada file sewaan, tanpa menyertakan ID sewa:

• Dapatkan File
• Dapatkan Metadata File
• Dapatkan Properti File
• Rentang Daftar
• Daftar Direktori dan File
• Salin File (Tidak diperlukan ID sewa untuk file sumber.)
• File Sewa (REST API) (Tidak diperlukan ID sewa untuk x-ms-lease-action: break.)

Tidak perlu menyertakan ID sewa untuk GET operasi pada file yang memiliki sewa aktif. Namun, semua GET operasi mendukung parameter sewa bersyarah. Dalam jenis parameter ini, operasi hanya dilanjutkan jika ID sewa yang disertakan dengan permintaan valid.

Semua operasi berbagi diizinkan pada berbagi yang menyertakan file dengan sewa aktif, termasuk Hapus Berbagi. Oleh karena itu, Anda dapat menghapus berbagi meskipun file di dalamnya memiliki sewa aktif.

Status sewa

Diagram berikut menunjukkan tiga status sewa, dan perintah atau peristiwa yang menyebabkan perubahan status sewa.

Sewa dapat berada di tiga negara bagian, berdasarkan apakah sewa dikunci atau tidak terkunci, dan apakah sewa dapat diperpanjang dalam keadaan tersebut. Tindakan sewa yang ditunjukkan dalam diagram sebelumnya menyebabkan transisi status.

• Available: Sewa tidak terkunci dan dapat diperoleh. Tindakan yang diizinkan: acquire.
• Leased: Sewa dikunci. Tindakan yang diizinkan: acquire (hanya ID sewa yang sama), change, , releasedan break.
• Broken: Sewa telah rusak. Tindakan yang diizinkan: acquire, release, dan break.

Perhatikan bahwa sewa tidak dapat diberikan untuk file dalam salinan bayangan berbagi, karena rekam jepret bersifat baca-saja. Meminta sewa terhadap file dalam salinan bayangan berbagi menghasilkan kode status 400 (Permintaan Buruk).

Jika sewa file dalam status Rusak dan operasi Put Range menulis ke file, status sewa akan berubah menjadi Tersedia. Namun, jika file memiliki atribut baca-saja yang ditetapkan, server akan mengembalikan konflik 409.

Properti file Last-Modified-Time tidak diperbarui oleh panggilan ke Lease File.

Tabel berikut menunjukkan hasil tindakan pada file dengan sewa di berbagai status sewa. Huruf (A), (B), dan (C) mewakili ID sewa, dan (X) mewakili ID sewa yang dihasilkan oleh Azure Files.

Hasil upaya penggunaan pada file berdasarkan status sewa

Tindakan	Tersedia	Sewaan (A)	Rusak (A)
Menulis dengan menggunakan (A)	Gagal (412)	Leased (A), penulisan berhasil	Gagal (412)
Menulis dengan menggunakan (B)	Gagal (412)	Gagal (409)	Gagal (412)
Tulis, tidak ada sewa yang ditentukan	Tersedia, penulisan berhasil	Gagal (412)	Tersedia, penulisan berhasil
Membaca dengan menggunakan (A)	Gagal (412)	Sewa (A), baca berhasil	Gagal (412)
Baca dengan menggunakan (B)	Gagal (412)	Gagal (409)	Gagal (412)
Baca, tidak ada sewa yang ditentukan	Tersedia, baca berhasil	Sewa (A), baca berhasil	Rusak (A), baca berhasil

Hasil operasi sewa pada file berdasarkan status sewa

Tindakan	Tersedia	Sewaan (A)	Rusak (A)
Acquire, tidak ada ID sewa yang diusulkan	Sewaan (X)	Gagal (409)	Sewaan (X)
Acquire (A)	Sewaan (A)	Sewaan (A)	Sewaan (A)
Acquire (B)	Sewa (B)	Gagal (409)	Sewa (B)
Break	Gagal (409)	Rusak (A)	Rusak (A)
Change, (A) ke (B)	Gagal (409)	Sewa (B)	Gagal (409)
Change, (B) ke (A)	Gagal (409)	Sewaan (A)	Gagal (409)
Change, (B) ke (C)	Gagal (409)	Gagal (409)	Gagal (409)
Release (A)	Gagal (409)	Tersedia	Tersedia
Release (B)	Gagal (409)	Gagal (409)	Gagal (409)

Lihat juga

• Mengotorisasi permintaan ke Azure Storage
• Status dan kode galat
• Azure Files kode kesalahan