Bagikan melalui

File Sewa

  • Artikel

Operasi 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 operasi Lease File 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

Protokol berbagi file yang diaktifkan Tersedia
SMB Ya
NFS Tidak ada

Minta

Permintaan Lease File dibangun sebagai berikut. Kami menyarankan agar Anda menggunakan HTTPS.

Metode Meminta URI Versi HTTP
MELETAKKAN https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1

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

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

Parameter URI

Anda dapat menentukan parameter tambahan berikut pada URI permintaan.

Parameter Deskripsi
timeout Fakultatif. 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.

Header permintaan Deskripsi
Authorization Diperlukan. Menentukan skema otorisasi, nama akun, dan tanda tangan. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage.
Date atau x-ms-date Diperlukan. Menentukan Waktu Universal Terkoordinasi (UTC) untuk permintaan tersebut. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage.
x-ms-version Fakultatif. 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 memutus 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 operasi acquire. Harus -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 Fakultatif. 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 header Authorization menentukan token OAuth. Nilai yang dapat diterima 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 header Authorization. Tersedia untuk versi 2022-11-02 dan yang lebih baru.
x-ms-allow-trailing-dot: { <Boolean> } Fakultatif. 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 Penamaan dan referensi berbagi, direktori, file, dan metadata.

Isi permintaan

Tidak.

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 myaccount:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=

Jawaban

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 menyertakan header dalam tabel berikut. Respons juga dapat mencakup header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1 .

Header respons 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 file yang terakhir dimodifikasi. 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 memutuskan sewa. 0 dikembalikan untuk jeda segera.
x-ms-request-id Mengidentifikasi permintaan yang dibuat secara unik, dan dapat digunakan untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat operasi API Pemecahan Masalah .
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 header x-ms-client-request-id, jika ada dalam permintaan. Nilainya paling banyak 1.024 karakter ASCII yang terlihat. Jika header x-ms-client-request-id tidak ada dalam permintaan, header tersebut tidak akan ada dalam respons.

Isi respons

Tidak.

Sampel respons

Berikut ini adalah contoh respons 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>

Otorisasi

Hanya pemilik akun yang dapat memanggil operasi ini.

Komentar

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:

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:

Tidak perlu menyertakan ID sewa untuk operasi GET pada file yang memiliki sewa aktif. Namun, semua operasi GET mendukung parameter sewa bersyarah. Dalam jenis parameter ini, operasi hanya berlanjut 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.

diagram yang memperlihatkan status sewa file dan pemicu perubahan status.FileLeaseStates

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, release, dan break.
  • Broken: Sewa telah rusak. Tindakan yang diizinkan: acquire, release, dan break.

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

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

Properti Last-Modified-Time file 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

Perbuatan 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) Leased (A), baca berhasil Gagal (412)
Membaca dengan menggunakan (B) Gagal (412) Gagal (409) Gagal (412)
Baca, tidak ada sewa yang ditentukan Tersedia, baca berhasil Leased (A), baca berhasil Rusak (A), baca berhasil

Hasil operasi sewa pada file berdasarkan status sewa

Perbuatan 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) Sewaan (B) Gagal (409) Sewaan (B)
Break Gagal (409) Rusak (A) Rusak (A)
Change, (A) ke (B) Gagal (409) Sewaan (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