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


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

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

См. также