Дескрипторы списка

Статья
03/29/2023

Операция List Handles возвращает список открытых дескрипторов в каталоге или файле. При необходимости он может рекурсивно перечислять открытые дескрипторы в каталогах и файлах. Этот API доступен начиная с версии 2018-11-09.

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

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

Запрос

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

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

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

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

Дополнительные сведения об ограничениях именования путей см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

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

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

Параметр	Описание
`marker`	Необязательный элемент. Строковое значение, определяющее часть списка, возвращаемую при выполнении следующей `List Handles` операции. Операция возвращает значение маркера в тексте ответа, если возвращенный список не был завершен. Затем можно использовать значение маркера в последующем вызове для запроса следующего набора элементов списка. Значение маркера непрозрачно для клиента.
`maxresults`	Необязательный элемент. Указывает максимальное количество дескрипторов, принятых для возвращаемых файлов или каталогов. Установка для `maxresults` значения меньше нуля или равного нулю приводит к возвращению кода ошибки 400 (неправильный запрос).
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций Файлы Azure.
`sharesnapshot`	Необязательный элемент. Параметр `sharesnapshot` является непрозрачным `DateTime` значением, которое при наличии указывает общий snapshot для запроса списка дескрипторов.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Обязательный для всех авторизованных запросов, необязательный для анонимных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.
`x-ms-recursive`	Необязательный элемент. Логическое значение, указывающее, должна ли операция также применяться к файлам и подкаталогам каталога, указанного в URI.
`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-адресе запроса. Дополнительные сведения см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

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

Нет.

Ответ

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

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

Успешная операция возвращает код состояния 200 (ОК). Сведения о кодах состояния см. в разделе Коды состояния и ошибок.

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

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

Заголовок ответа	Описание
`Content-Type`	Задает формат, в котором возвращаются результаты. Сейчас задано значение `application/xml`.
`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` отсутствует в запросе, этот заголовок не будет присутствовать в ответе.

Текст ответа

XML-ответ имеет следующий формат. Обратите внимание, что Markerэлементы , ShareSnapshotи MaxResults присутствуют только в том случае, если они указаны в URI запроса. Элемент NextMarker имеет значение только в том случае, если результаты списка не завершены.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults>
    <HandleList>
        <Handle>
            <HandleId>handle-id</HandleId>
            <Path>file-or-directory-name-including-full-path</Path>
            <FileId>file-id</FileId>
            <ParentId>parent-file-id</ParentId>
            <SessionId>session-id</SessionId>
            <ClientIp>client-ip</ClientIp>
            <OpenTime>opened-time</OpenTime>
            <LastReconnectTime>lastreconnect-time</LastReconnectTime>
            <AccessRightList>
                <AccessRight>Read</AccessRight>
                <AccessRight>Write</AccessRight>
                <AccessRight>Delete</AccessRight>
            </AccessRightList>
        </Handle>
        ...
    </HandleList>
    <NextMarker>next-marker</NextMarker>
</EnumerationResults>

В следующей таблице описаны поля текста ответа:

Поле	Описание	Назначение
`HandleId`	Идентификатор дескриптора службы XSMB, UINT64.	Используется для идентификации дескриптора.
`Path`	Имя файла, включая полный путь, начиная с корневого каталога общей папки. Строка.	Используется для идентификации имени объекта, для которого открыт дескриптор.
`ClientIp`	IP-адрес клиента, открывший дескриптор. Строка.	Используется для принятия решения о возможной утечке дескриптора.
`OpenTime`	Был открыт дескриптор времени (UTC). `DateTime` как Строка.	Используется для принятия решения о возможной утечке дескриптора. Дескрипторные ручки, как правило, были открыты в течение длительного времени.
`LastReconnectTime`	Был открыт дескриптор времени (UTC). `DateTime` как Строка.	Используется для выбора повторного открытия дескриптора после отключения клиента или сервера из-за сетевых или других сбоев. Поле включается в текст ответа только в том случае, если произошло событие отключения и дескриптор был вновь открыт.
`FileId`	Идентификатор файла, UINT64.	`FileId` уникально идентифицирует файл. Это полезно при переименовании, так как `FileId` не изменяется.
`ParentId`	Идентификатор родительского файла, UINT64.	`ParentId` уникально идентифицирует каталог. Это полезно при переименовании, так как `ParentId` не изменяется.
`SessionId`	Идентификатор сеанса SMB, указывающий контекст, в котором был открыт дескриптор файла. UINT64.	`SessionId` включается в журналы средства просмотра событий при принудительном отключении сеансов. Это позволяет связать определенный пакет дескрипторов утечки с конкретным сетевым инцидентом.
`AccessRightList`	Разрешения на доступ, предоставленные открытому дескриптору для файла или каталога.	Доступно в службе версии 2023-01-03 и более поздних. Используется для запроса разрешений на доступ к файлу или каталогу с помощью различных открытых дескрипторов. Возможные значения: READ, WRITE и DELETE или сочетание этих значений.
`NextMarker`	Строка, описывающая следующий дескриптор для перечисления. Он возвращается, когда для выполнения запроса необходимо указать дополнительные дескрипторы.	Строка используется в последующих запросах на перечисление оставшихся дескрипторов. Отсутствие `NextMarker` указывает на то, что были перечислены все соответствующие дескрипторы.

В версиях 2021-12-02 и более поздних будет кодировать процент (согласно RFC 2396) все Path значения элементов, List Handles содержащие символы, недопустимые в XML (в частности, U+FFFE или U+FFFF). При кодировании Path элемент будет содержать Encoded=true атрибут . Обратите внимание, что это происходит только для значений Path элементов, содержащих недопустимые символы в XML, а не для остальных Path элементов в ответе.

Авторизация

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