Файл аренды
Операция 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
.
Следующие операции выполняются в арендованном файле без включения идентификатора аренды:
- получение файла
- получение метаданных файла
- получения свойств файла
- диапазоны списков
- каталогов списков и файлов
- копирование файла (идентификатор аренды не требуется для исходного файла.)
-
файл аренды (REST API) (идентификатор аренды не требуется для
x-ms-lease-action: break
.)
Не обязательно включить идентификатор аренды для операций 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) |