Файл аренды

Операция Lease File создает и управляет блокировкой файла для операций записи и удаления. Lease File поддерживается для версии 2019-02-02 и более поздних версий.

Операцию можно вызвать Lease File в одном из следующих режимов:

• Acquire — запрос новой аренды;
• Change — изменение идентификатора существующей аренды;
• Release, чтобы освободить аренду, если она больше не нужна, чтобы другой клиент сразу же получил аренду для файла.
• Break, чтобы принудительно прекратить аренду, но убедиться, что другой клиент не может получить новую аренду до истечения текущего периода аренды.

Доступность протокола

Включенный протокол общей папки	Доступно
SMB
NFS

Запрос

Запрос можно создать Lease File следующим образом. Рекомендуется использовать протокол HTTPS.

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
Put	https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease	HTTP/1.1

Замените компоненты пути, показанный в URI запроса, следующим образом:

Компонент path	Описание
myaccount	Имя учетной записи хранения.
myshare	Имя файлового ресурса.
mydirectorypath	Необязательный элемент. Путь к каталогу.
myfile	Имя файла.

Параметры универсального кода ресурса (URI)

В URI запроса можно указать следующий дополнительный параметр.

Параметр	Описание
timeout	Необязательный элемент. Параметр timeout указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций Файлы Azure.

Заголовки запросов

В следующей таблице перечислены обязательные и необязательные заголовки запросов.

Заголовок запроса	Описание
Authorization	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
Date или x-ms-date	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
x-ms-version	Необязательный элемент. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
x-ms-lease-id: <ID>	Обязательно при продлении, изменении или освобождении аренды. Значение можно указать в любом допустимом x-ms-lease-id формате строки GUID. Список допустимых форматов см. в разделе Конструктор GUID (строка).
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break>	acquire: запрашивает новую аренду. Если у файла нет активной аренды, Файлы Azure создает аренду файла и возвращает новый идентификатор аренды. Если файл имеет активную аренду, вы можете запросить новую аренду только с помощью идентификатора активной аренды. change: изменяет идентификатор аренды активной аренды. Объект change должен включать текущий идентификатор аренды в x-ms-lease-idи новый идентификатор аренды в x-ms-proposed-lease-id. release: освобождает аренду. Вы можете освободить аренду, если идентификатор аренды, указанный в запросе, совпадает с идентификатором, связанным с файлом. Освобождение аренды позволяет другому клиенту немедленно получить аренду для файла, как только выпуск будет завершен. break: прерывает аренду, если файл имеет активную аренду. Любой авторизованный запрос может прервать аренду. Запрос не требуется для указания соответствующего идентификатора аренды. Бесконечная аренда немедленно нарушается.
x-ms-lease-duration: -1	Разрешено и требуется только для acquire операции. Требуется иметь значение -1, чтобы указать аренду, срок действия которого не истекает.
x-ms-proposed-lease-id: <ID>	Необязательный для acquireи обязательный для change. Идентификатор предлагаемой аренды в формате строки GUID. Файлы Azure возвращает значение 400 (Invalid request) , если предлагаемый идентификатор аренды не в правильном формате. Список допустимых форматов см. в разделе Конструктор GUID (строка).
x-ms-client-request-id	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.
x-ms-file-request-intent	Требуется, если Authorization заголовок указывает токен OAuth. Допустимое значение — backup. Этот заголовок указывает, что Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action или должны быть предоставлены, если они включены в политику RBAC, назначенную удостоверению, которое авторизовано с помощью заголовка Authorization . Доступно для версии 2022-11-02 и более поздних версий.
x-ms-allow-trailing-dot: { <Boolean> }	Необязательный элемент. Версия 2022-11-02 и более поздние версии. Логическое значение указывает, следует ли обрезать завершающую точку в URL-адресе запроса. Дополнительные сведения см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

Текст запроса

Нет.

Пример запроса

В следующем примере показан запрос на приобретение аренды.

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=  

Ответ

Ответ включает код состояния HTTP и набор заголовков ответа.

Код состояния

Коды состояния успешного выполнения для операций аренды.

• Acquire: успешная операция возвращает код состояния 201 (создано).
• Change: успешная операция возвращает код состояния 200 (ОК).
• Release: успешная операция возвращает код состояния 200 (ОК).
• Break: успешная операция возвращает код состояния 202 (Принято).

Сведения о кодах состояния см. в разделе Коды состояния и ошибок.

Заголовки ответов

Ответ для этой операции включает следующие заголовки. Ответ также может содержать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.

Синтаксис	Описание
ETag	Содержит значение, которое можно использовать для условного выполнения операций в кавычках. Операция Lease File не изменяет это свойство.
Last-Modified	Дата и время последнего изменения файла. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Любая операция записи в файл, включая обновления метаданных или свойств файла, изменяет время последнего изменения файла. Операция Lease File не изменяет это свойство.
x-ms-lease-id: <id>	При запросе аренды Файлы Azure возвращает уникальный идентификатор аренды. Пока аренда активна, необходимо включить идентификатор аренды с любым запросом на запись в файл, изменение или освобождение аренды. Успешная операция продления также возвращает идентификатор активной аренды.
x-ms-lease-time: seconds	Возвращается только для успешного запроса на прерывание аренды. 0 возвращается для немедленного прерывания.
x-ms-request-id	Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок запроса. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
x-ms-version	Указывает версию Файлы Azure, используемую для выполнения запроса.
Date	Значение даты и времени в формате UTC, указывающее время, когда был инициирован ответ. Служба создает это значение.
x-ms-client-request-id	Может использоваться для устранения неполадок с запросами и соответствующими ответами. Значение этого заголовка равно значению заголовка x-ms-client-request-id , если он присутствует в запросе. Значение равно не более 1024 видимых символов ASCII. Если заголовок x-ms-client-request-id отсутствует в запросе, он не будет присутствовать в ответе.

Текст ответа

Нет.

Пример ответа

Ниже приведен пример ответа на запрос приобретения аренды.

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>  

Авторизация

Владелец учетной записи может вызвать эту операцию. Кроме того, это может сделать любой клиент с подписанным URL-адресом, имеющий разрешение на запись в этот файл или его общую папку.

Комментарии

Аренда файла обеспечивает монопольный доступ на запись и удаление файла. Для записи в файл с активной арендой клиент должен включить идентификатор активной аренды в запрос на запись. Аренда предоставляется на неограниченный срок.

Когда клиент приобретает аренду, возвращается идентификатор аренды. Файлы Azure создает идентификатор аренды, если он не указан в запросе на получение. Клиент может использовать этот идентификатор аренды для изменения идентификатора аренды или освобождения аренды.

Когда аренда активна, идентификатор аренды необходимо включать в запрос любой из следующих операций:

• Создание файла
• Установка метаданных файла
• Задание свойств файла
• Удаление файла
• Диапазон Put
• Копировать файл (идентификатор аренды требуется для целевого файла).)

Если идентификатор аренды не включен, эти операции завершаются ошибкой в арендованном файле с 412 – Precondition failed.

Следующие операции с арендованным файлом успешно выполняются без включения идентификатора аренды:

• Получение данных из файла
• Получение метаданных файла
• Получение свойств файла
• Диапазоны списка
• Список каталогов и файлов
• Копировать файл (для исходного файла не требуется идентификатор аренды).)
• Файл аренды (REST API) (идентификатор аренды не требуется для x-ms-lease-action: break.)

Необязательно включать идентификатор аренды для GET операций с файлом с активной арендой. Однако все GET операции поддерживают параметр условной аренды. В этом типе параметра операция продолжается только в том случае, если идентификатор аренды, включенный в запрос, является допустимым.

Все операции с общим ресурсом разрешены в общей папке, которая включает файлы с активной арендой, включая удаление общей папки. Таким образом, вы можете удалить общую папку, даже если у файлов в ней есть активные аренды.

Состояния аренды

На следующей схеме показаны три состояния аренды, а также команды или события, вызывающие изменение состояния аренды.

Аренда может находиться в трех штатах в зависимости от того, заблокирована или разблокирована аренда, а также от того, возобновляется ли аренда в этом состоянии. Действия аренды, показанные на предыдущей схеме, вызывают переходы состояния.

• Available: аренда разблокирована и может быть приобретена. Допустимое действие: acquire.
• Leased: аренда заблокирована. Допустимые действия: acquire (только с одинаковым идентификатором аренды), change, releaseи break.
• Broken: аренда нарушена. Допустимые действия: acquire, releaseи break.

Обратите внимание, что аренда не может быть предоставлена для файла в общей папке snapshot, так как моментальные снимки доступны только для чтения. Запрос аренды для файла в общей папке snapshot приводит к коду состояния 400 (недопустимый запрос).

Если аренда файла находится в состоянии Неработает , а операция Put Range выполняет запись в файл, состояние аренды изменится на Доступно. Однако если в файле задан атрибут только для чтения, сервер вернет конфликт 409.

Свойство файла Last-Modified-Time не обновляется вызовами Lease File.

В следующих таблицах показаны результаты действий с файлами с арендой в различных состояниях аренды. Буквы (A), (B) и (C) представляют идентификаторы аренды, а (X) — идентификатор аренды, созданный Файлы Azure.

Результаты попыток использования файлов по состоянию аренды

Действие	Доступно	Арендовано (А)	Прекращено (А)
Запись с помощью (A)	Ошибка (412)	Арендовано (А), успешная запись	Ошибка (412)
Запись с помощью (B)	Ошибка (412)	Сбой (409)	Ошибка (412)
Запись, аренда не указана	Доступно, успешная запись	Ошибка (412)	Доступно, успешная запись
Чтение с помощью (A)	Ошибка (412)	Арендовано (А), успешное чтение	Ошибка (412)
Чтение с помощью (B)	Ошибка (412)	Сбой (409)	Ошибка (412)
Чтение, аренда не указана	Доступно, успешное чтение	Арендовано (А), успешное чтение	Прекращение (А), успешное чтение

Результаты операций аренды для файлов по состоянию аренды

Действие	Доступно	Арендовано (А)	Прекращено (А)
Acquire — предлагаемый идентификатор аренды отсутствует	Арендовано (X)	Сбой (409)	Арендовано (X)
Acquire (A)	Арендовано (А)	Арендовано (А)	Арендовано (А)
Acquire (B)	Арендовано (B)	Сбой (409)	Арендовано (B)
Break	Сбой (409)	Прекращено (А)	Прекращено (А)
Change, (A) в (B)	Сбой (409)	Арендовано (B)	Сбой (409)
Change, (B) в (A)	Сбой (409)	Арендовано (А)	Сбой (409)
Change, (B) в (C)	Сбой (409)	Сбой (409)	Сбой (409)
Release (A)	Сбой (409)	Доступно	Доступно
Release (B)	Сбой (409)	Сбой (409)	Сбой (409)

См. также раздел

• Авторизация запросов к службе хранилища Azure
• Коды состояний и ошибок
• коды ошибок Файлы Azure