Popisovače seznamu

Článek
02/20/2025

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
NFS

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é

Operace se soubory
operace v adresářích

Sdílet prostřednictvím