Аренда общей папки

Операция Lease Share устанавливает и управляет блокировкой общей папки Azure или общей папки snapshot. Этот API полностью поддерживается, но это устаревший API управления. Вместо этого используйте общие папки — аренда, предоставляемые поставщиком ресурсов хранилища (Microsoft.Storage). Дополнительные сведения о программном взаимодействии с FileShare ресурсами с помощью поставщика ресурсов хранилища см. в статье Операции с общими папками.

Длительность блокировки может составлять 15–60 секунд либо быть бесконечной. Операцию можно вызвать Lease Share в одном из следующих режимов:

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

Примечание

Операция Lease Share доступна в версии 2020-02-10 и более поздних.

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

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

Запрос

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
PUT	https://myaccount.file.core.windows.net/myshare?comp=lease&restype=share	HTTP/1.1
PUT	https://myaccount.file.core.windows.net/myshare?comp=lease&sharesnapshot=<DateTime>&restype=share	HTTP/1.1

Параметры универсального кода ресурса (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: <action>	acquire: запрашивает новую аренду. Если у общей папки нет активной аренды, Файлы Azure создает аренду общей папки и возвращает новый идентификатор аренды. Если общая папка имеет активную аренду, вы можете запросить новую аренду только с помощью идентификатора активной аренды. Однако можно указать новый x-ms-lease duration, включая отрицательный (-1) для аренды, срок действия которого не истекает. renew: продлевает аренду. Вы можете продлить аренду, если идентификатор аренды, указанный в запросе, совпадает с идентификатором, связанным с общей папкой. Обратите внимание, что вы можете продлить аренду, даже если срок ее действия истек, если общая папка не была снова арендовано после истечения срока аренды. При продлении аренды срок действия начинается заново. change: изменяет идентификатор активной аренды. Объект change должен включать текущий идентификатор аренды в x-ms-lease-idи новый идентификатор аренды в x-ms-proposed-lease-id. release: освобождает аренду. Вы можете освободить аренду, если идентификатор аренды, указанный в запросе, совпадает с идентификатором, связанным с общей папкой. Освобождение аренды позволяет другому клиенту немедленно получить аренду для общей папки, как только выпуск будет завершен. break: прервать аренду, если у общей папки есть активная аренда. После разрыва аренды ее нельзя продлить. Любой авторизованный запрос может прервать аренду. Запрос не требуется для указания соответствующего идентификатора аренды. Если аренда нарушена, период перерыва аренды может пройти, и break и release являются единственными операциями, которые можно выполнить в файловом ресурсе в течение этого времени. После успешного прекращения аренды ответ указывает интервал в секундах, прежде чем можно будет приобрести новую аренду. Прекращенная аренда также может быть освобождена. Клиент может немедленно получить аренду общей папки, которая была освобождена.
x-ms-lease-break-period: N	Необязательный элемент. break Для операции это предлагаемый срок аренды должен продолжаться до того, как она будет нарушена в секундах в диапазоне от 0 до 60. Этот период перерыва используется только в том случае, если он меньше времени, оставшегося в аренде. В противном случае используется оставшееся время аренды. Новая аренда недоступна до истечения периода перерыва, но аренда может храниться дольше, чем период перерыва. Если этот заголовок не отображается с операцией break , по истечении оставшегося периода аренды будет прервана аренда с фиксированной длительностью, а бесконечная аренда немедленно прерывается.
x-ms-lease-duration: -1	Обязательно для acquire. Указывает срок аренды в секундах или отрицательное число (-1) для бесконечной аренды. Конечная аренда может находиться в пределах от 15 до 60 секунд. Длительность аренды нельзя изменить с помощью renew или change.
x-ms-proposed-lease-id: <ID>	Необязательный для acquireи обязательный для change. Идентификатор предлагаемой аренды в формате строки GUID. Хранилище BLOB-объектов Azure возвращает значение 400 (Invalid request) , если предлагаемый идентификатор аренды не в правильном формате. Список допустимых форматов см. в разделе Конструктор GUID (строка).
Origin	Необязательный элемент. Указывает источник, от которого выдан запрос. Наличие этого заголовка приводит к появлению в ответе заголовков совместного использования ресурсов (CORS). Дополнительные сведения см. в разделе Поддержка CORS для служб хранилища .
x-ms-client-request-id	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.

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

Нет.

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

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

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare?restype=share&comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2020-02-10  
x-ms-lease-action: acquire  
x-ms-lease-duration: -1  
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-date: Thu, 26 Jan 2012 23:30:18 GMT  
Authorization: SharedKey testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=  

Ответ

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

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

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

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

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

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

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

Синтаксис	Описание
ETag	Для ETag общей папки.
Last-Modified	Возвращает дату и время последнего изменения общей папки. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Любая операция, изменяющая общую папку, ее свойства или метаданные, обновляет время последнего изменения. Сюда входит настройка разрешений для общей папки. Операции с большими двоичными объектами не влияют на время последнего изменения общей папки.
x-ms-lease-id: <id>	При запросе аренды Файлы Azure возвращает уникальный идентификатор аренды. Пока аренда активна, необходимо включить идентификатор аренды в любой запрос на удаление общей папки, продление, изменение или освобождение аренды. Успешная операция продления также возвращает идентификатор активной аренды.
x-ms-lease-time: seconds	Приблизительное время, оставшееся до истечения срока аренды в секундах. Этот заголовок возвращается только для успешного запроса прекращения аренды. Если разрыв является немедленным, 0 возвращается значение .
x-ms-request-id	Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
x-ms-version	Указывает версию API FileREST, используемого для выполнения запроса.
Date	Значение даты и времени в формате UTC, указывающее время, когда был инициирован ответ. Служба создает это значение.
Access-Control-Allow-Origin	Возвращается, если запрос содержит Origin заголовок, а CORS включен с правилом сопоставления. В случае совпадения этот заголовок возвращает значение заголовка источника запроса.
Access-Control-Expose-Headers	Возвращается, если запрос содержит Origin заголовок, а CORS включен с правилом сопоставления. Возвращает список заголовков ответа, которые должны быть предоставлены клиенту или отправителю запроса.
Access-Control-Allow-Credentials	Возвращается, если запрос включает заголовок Origin , а CORS включен с правилом сопоставления, которое не разрешает все источники. Этот заголовок имеет значение true.
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: 2020-02-10  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: Thu, 26 Jan 2012 23:30:18 GMT  

Авторизация

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

Комментарии

Аренда общей папки обеспечивает монопольный доступ к общей папке для удаления. Операции получения общей папки будут успешными для арендованного файлового ресурса без включения идентификатора аренды. Для операций установки общей папки потребуется идентификатор аренды общей папки. Если идентификатор аренды не включен в операции набора файлового ресурса, операция завершается ошибкой 412 (сбой предварительного условия). Аренда предоставляется на период, указанный при получении аренды, который может составлять от 15 до 60 секунд или бесконечное время.

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

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

Состояние продления	Заблокированная аренда	Разблокированная аренда
Возобновляемая аренда	Арендовано	Срок действия истек
Невозобновляемая аренда	Критическое	Прекращенная, доступна

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

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

Свойство общей папки Last-Modified-Time не обновляется вызовами Lease Share.

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

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

Действие	Доступно	Арендовано (А)	Прекращение (А)	Прекращено (А)	Истек срок (А)
Удаление с помощью (A)	Ошибка (412)	Арендовано (А), успешное удаление	Прекращено (A), успешное удаление	Ошибка (412)	Ошибка (412)
Удалить с помощью (B)	Ошибка (412)	Сбой (409)	Ошибка (412)	Ошибка (412)	Ошибка (412)
Удаление, аренда не указана	Доступно, успешное удаление	Ошибка (412)	Ошибка (412)	Доступно, успешное удаление	Доступно, успешное удаление
Другие операции с (A)	Ошибка (412)	Арендовано (А), операция выполнена успешно	Прекращено (A), операция выполнена успешно	Ошибка (412)	Ошибка (412)
Другие операции с (B)	Ошибка (412)	Сбой (409)	Сбой (409)	Ошибка (412)	Ошибка (412)
Операции, аренда не указана	Доступно, операция выполнена успешно	Арендовано (А), операция выполнена успешно	Прекращено (A), операция выполнена успешно	Прекращено (A), операция выполнена успешно	Срок действия истек (A), операция выполнена успешно

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

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