Поделиться через

Файл аренды

  • Статья

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

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

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

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

Протокол общей папки с включенным доступом Доступный
SMB Да
NFS Нет

Просьба

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

Метод URI запроса ВЕРСИЯ HTTP
КЛАСТЬ 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 (String).
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 (String).
x-ms-client-request-id Необязательный. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-kibibyte (KiB), записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitor Azure Files.
x-ms-file-request-intent Требуется, если заголовок Authorization указывает токен OAuth. Допустимое значение равно backup. Этот заголовок указывает, что Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action или Microsoft.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 myaccount: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>

Авторизация

Только владелец учетной записи может вызвать эту операцию.

Замечания

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

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

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

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

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

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

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

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

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

диаграмма с состояниями аренды файлов и триггерами изменений состояния.

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

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

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

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

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

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

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

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

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

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

См. также