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

Статья
02/21/2025

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

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

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

Просьба

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

Метод	URI запроса	ВЕРСИЯ HTTP
ПОЛУЧИТЬ	`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` значением, которое при наличии указывает моментальный снимок общего ресурса для запроса списка дескрипторов.

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

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

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

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

Никакой.

Ответ

Ответ включает код состояния 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 имеет значение, только если результаты списка не завершены.

ClientName поле в ответе является необязательным и возвращается только в том случае, если он доступен для службы.

<?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>
            <ClientName>client-name</ClientName>
            <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-адрес клиента, открывший дескриптор. Струна.	Используется для определения утечки дескриптора.
`ClientName`	Необязательное поле. Поддерживается в 2024-02-04 и более поздних версиях. Имя клиента (рабочая станция или имя пользователя ОС), открывающее дескриптор. Струна.	Используется для определения утечки дескриптора.
`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 и более поздних версиях List Handles будет кодировать процент (на RFC 2396) все значения элементов Path, содержащие символы, недопустимые в XML (в частности, U+FFFE или U+FFFFFF). При кодировании элемент Path будет включать атрибут Encoded=true. Обратите внимание, что это будет происходить только для значений элементов Path, содержащих символы, недопустимые в XML, а не остальные Path элементы в ответе.

ClientName поддерживается в версии 2024-02-04 и более поздних версиях.

Авторизация

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

Замечания

HandleId — это идентификатор дескриптора на стороне службы, отличный от идентификатора дескриптора клиента. Сопоставление между ними возможно на клиенте.

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