Дескриптор списка
Операция 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.
Общие заголовки
Текст ответа
Формат 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
— это идентификатор дескриптора на стороне службы, отличный от идентификатора дескриптора клиента. Сопоставление между ними возможно на клиенте.