Sdílet prostřednictvím


Popisovače seznamu

Operace List Handles vrátí seznam otevřených popisovačů v adresáři nebo souboru. Volitelně může rekurzivně vytvořit výčet otevřených popisovačů v adresářích a souborech. Toto rozhraní API je k dispozici od verze 2018-11-09.

Dostupnost protokolu

Povolený protokol sdílené složky K dispozici
SMB Ano
NFS Bez

Prosba

Požadavek List Handles je vytvořen následujícím způsobem. Doporučujeme používat PROTOKOL HTTPS.

Metoda Identifikátor URI požadavku Verze HTTP
DOSTAT https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles HTTP/1.1

Součásti cesty zobrazené v identifikátoru URI požadavku nahraďte vlastními, a to následujícím způsobem:

Komponenta Path Popis
myaccount Název vašeho účtu úložiště.
myshare Název sdílené složky.
mydirectorypath Volitelný. Cesta k adresáři.
myfileordirectory Název souboru nebo adresáře.

Podrobnosti o omezeních pojmenování cest najdete v tématu Pojmenování a odkazování na sdílené složky, adresáře, soubory a metadata.

Parametry identifikátoru URI

Pro identifikátor URI můžete zadat následující další parametry.

Parametr Popis
marker Volitelný. Řetězcová hodnota, která identifikuje část seznamu, která se má vrátit, pomocí další operace List Handles. Operace vrátí hodnotu značky v textu odpovědi, pokud vrácený seznam nebyl dokončen. Hodnotu značky pak můžete použít v následném volání a požádat o další sadu položek seznamu.

Hodnota značky je pro klienta neprůhelní.
maxresults Volitelný. Určuje maximální počet popisovačů přijatých u souborů nebo adresářů, které se mají vrátit.

Nastavení maxresults na hodnotu menší nebo rovno nule způsobí chybu s kódem odpovědi 400 (Chybný požadavek).
timeout Volitelný. Parametr timeout se vyjadřuje v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace azure Files.
sharesnapshot Volitelný. Parametr sharesnapshot je neprůzná DateTime hodnota, která při výskytu určuje snímek sdílené složky, který se má dotazovat na seznam popisovačů.

Hlavičky požadavku

Následující tabulka popisuje povinné a volitelné hlavičky požadavků.

Hlavička požadavku Popis
Authorization Požadovaný. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků na službu Azure Storage.
Date nebo x-ms-date Požadovaný. Určuje standard UTC (Coordinated Universal Time) pro požadavek. Další informace najdete v tématu Autorizace požadavků na službu Azure Storage.
x-ms-version Povinné pro všechny autorizované žádosti, volitelné pro anonymní žádosti. Určuje verzi operace, která se má pro tento požadavek použít. Další informace najdete v tématu Správa verzí pro služby Azure Storage.
x-ms-client-request-id Volitelný. Poskytuje hodnotu vygenerovanou klientem, neprůshlenou hodnotou s limitem znaků 1 kibibajtů (KiB), který je zaznamenán v protokolech při konfiguraci protokolování. Důrazně doporučujeme použít tuto hlavičku ke korelaci aktivit na straně klienta s požadavky, které server přijímá. Další informace najdete v tématu Monitorování služby Azure Files.
x-ms-recursive Volitelný. Logická hodnota, která určuje, jestli má operace platit také pro soubory a podadresáře adresáře zadaného v identifikátoru URI.
x-ms-file-request-intent Vyžaduje se, pokud hlavička Authorization určuje token OAuth. Přijatelná hodnota je backup. Tato hlavička určuje, že Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action nebo Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action by měly být uděleny, pokud jsou zahrnuty do zásad RBAC přiřazené k identitě, která je autorizovaná pomocí hlavičky Authorization. K dispozici pro verzi 2022-11-02 a novější.
x-ms-allow-trailing-dot: { <Boolean> } Volitelný. Verze 2022-11-02 a novější. Logická hodnota určuje, jestli by se měla oříznout koncová tečka v adrese URL požadavku, nebo ne. Další informace najdete v tématu Pojmenování a odkazování na sdílené složky, adresáře, soubory a metadata.

Text požadavku

Žádný.

Odpověď

Odpověď obsahuje stavový kód HTTP, sadu hlaviček odpovědí a text odpovědi ve formátu XML.

Stavový kód

Úspěšná operace vrátí stavový kód 200 (OK). Informace o stavových kódech naleznete v tématu Stav a kódy chyb.

Hlavičky odpovědi

Odpověď pro tuto operaci obsahuje hlavičky v následující tabulce. Odpověď může obsahovat také další standardní hlavičky HTTP. Všechny standardní hlavičky odpovídají specifikaci protokolu HTTP/1.1.

Běžná záhlaví

Hlavička odpovědi Popis
Content-Type Určuje formát, ve kterém se vrátí výsledky. V současné době je tato hodnota application/xml.
x-ms-request-id Tato hlavička jednoznačně identifikuje požadavek, který byl proveden, a lze ho použít k řešení potíží s požadavkem. Další informace najdete v tématu řešení potíží s operacemi rozhraní API.
x-ms-version Označuje verzi služby Azure Files použitou ke spuštění požadavku.
Date Hodnota data a času UTC, která označuje čas, kdy byla odpověď zahájena. Služba vygeneruje tuto hodnotu.
x-ms-client-request-id Tato hlavička slouží k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě hlavičky x-ms-client-request-id, pokud se nachází v požadavku. Hodnota je maximálně 1024 viditelných znaků ASCII. Pokud v požadavku není hlavička x-ms-client-request-id, nebude tato hlavička v odpovědi k dispozici.

Text odpovědi

Formát odpovědi XML je následující. Všimněte si, že prvky Marker, ShareSnapshota MaxResults jsou k dispozici pouze v případě, že jste je zadali na identifikátoru URI požadavku. Prvek NextMarker má hodnotu pouze v případě, že výsledky seznamu nejsou dokončeny.

ClientName pole v odpovědi je volitelné a vrátí se pouze v případě, že je služba dostupná.

<?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>

Následující tabulka popisuje pole textu odpovědi:

Pole Popis Účel
HandleId ID popisovače služby XSMB, UINT64 Používá se k identifikaci popisovače.
Path Název souboru, včetně úplné cesty, počínaje kořenem sdílené složky. Řetězec. Slouží k identifikaci názvu objektu, pro který je popisovač otevřen.
ClientIp IP adresa klienta, která otevřela popisovač. Řetězec. Používá se k rozhodnutí, jestli by mohl dojít k úniku rukojeti.
ClientName Volitelné pole. Podporováno ve verzi 2024-02-04 a novějších. Název klienta (pracovní stanice nebo uživatelské jméno operačního systému), který otevřel popisovač. Řetězec. Používá se k rozhodnutí, jestli by mohl dojít k úniku rukojeti.
OpenTime Časový popisovač byl otevřen (UTC). DateTime jako řetězec. Používá se k rozhodnutí, jestli mohlo dojít k úniku rukojeti. Nevracené úchyty jsou obvykle otevřené po dlouhou dobu.
LastReconnectTime Časový popisovač byl otevřen (UTC). DateTime jako řetězec. Používá se k rozhodnutí, jestli se popisovač znovu otevřel po odpojení klienta nebo serveru kvůli síťovým nebo jiným chybám. Pole je součástí textu odpovědi pouze v případě, že došlo k události odpojení a popisovač byl znovu otevřen.
FileId ID souboru, UINT64. FileId soubor jednoznačně identifikuje. Je užitečné při přejmenování, protože FileId se nezmění.
ParentId ID nadřazeného souboru, UINT64. ParentId jednoznačně identifikuje adresář. To je užitečné při přejmenování, protože ParentId se nezmění.
SessionId ID relace SMB, které určuje kontext, ve kterém byl otevřen popisovač souboru. UINT64. SessionId je součástí protokolů prohlížeče událostí, když jsou relace vynuceně odpojeny. Umožňuje přidružit konkrétní dávku nevracených popisovačů ke konkrétnímu síťovému incidentu.
AccessRightList Přístupová oprávnění udělená otevřenému popisovači v souboru nebo adresáři. K dispozici ve verzi 2023-01-03 a novější.

Používá se k dotazování na přístupová oprávnění uložená v souboru nebo adresáři různými otevřenými popisovači. Možné hodnoty jsou READ, WRITE a DELETE nebo kombinace těchto hodnot.
NextMarker Řetězec, který popisuje další popisovač, který se má vypisovat. Vrátí se, když je potřeba uvést další popisovače, aby bylo možné žádost dokončit. Řetězec se použije v následných požadavcích k výpisu zbývajících popisovačů. Absence NextMarker značí, že byly uvedeny všechny relevantní popisovače.

Ve verzích 2021-12-02 a novějších bude List Handles kódovat procenta (na RFC 2396) všechny hodnoty prvků Path, které obsahují neplatné znaky v jazyce XML (konkrétně U+FFFE nebo U+FFFF). Pokud je kódován, element Path bude obsahovat atribut Encoded=true. Všimněte si, že k tomu dojde pouze pro hodnoty elementu Path obsahující znaky neplatné v jazyce XML, nikoli zbývající Path elementy v odpovědi.

ClientName je podporována ve verzi 2024-02-04 a novější.

Oprávnění

Tuto operaci může volat pouze vlastník účtu.

Poznámky

HandleId je ID popisovače na straně služby, které se liší od ID popisovače klienta. Mapování mezi těmito dvěma je možné u klienta.

Viz také