Popisovače seznamu

Článek
06/01/2023

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čů adresářů a souborů. Toto rozhraní API je k dispozici od verze z 9. 11. 2018.

Dostupnost protokolu

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

Žádost

Požadavek můžete sestavit List Handles následujícím způsobem. Doporučuje se https.

Metoda	Identifikátor URI žádosti	Verze PROTOKOLU HTTP
`GET`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles`	HTTP/1.1

Následujícím způsobem nahraďte komponenty cesty uvedené v identifikátoru URI požadavku vlastními:

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

Podrobnosti o omezeních pojmenování cest najdete v tématu Pojmenování sdílených složek, adresářů, souborů a metadat a odkazování na nich.

Parametry identifikátoru URI

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

Parametr	Popis
`marker`	Nepovinný parametr. Řetězcová hodnota, která identifikuje část seznamu, která má být vrácena při další `List Handles` operaci. Operace vrátí hodnotu značky v těle odpovědi, pokud vrácený seznam nebyl dokončený. Hodnotu značky pak můžete použít v následném volání a vyžádat si další sadu položek seznamu. Hodnota značky je pro klienta neprůžná.
`maxresults`	Nepovinný parametr. Určuje maximální počet popisovačů souborů nebo adresářů, které se mají vrátit. Pokud `maxresults` nastavíte hodnotu menší nebo rovnou nule, zobrazí se kód odpovědi na chybu 400 (Chybný požadavek).
`timeout`	Nepovinný parametr. Parametr se `timeout` vyjadřuje v sekundách. Další informace najdete v tématu Nastavení časových limitů pro operace Azure Files.
`sharesnapshot`	Nepovinný parametr. Parametr `sharesnapshot` je neprůsložná `DateTime` hodnota, která pokud je k dispozici, určuje snímek sdílené složky, který se má dotazovat na seznam popisovačů.

Hlavičky požadavku

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

Hlavička požadavku	Popis
`Authorization`	Povinná hodnota. Určuje schéma autorizace, název účtu a podpis. Další informace najdete v tématu Autorizace požadavků do služby Azure Storage.
`Date` nebo `x-ms-date`	Povinná hodnota. Určuje formát UTC (Coordinated Universal Time). Další informace najdete v tématu Autorizace požadavků do služby 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`	Nepovinný parametr. Poskytuje klientem vygenerovanou neprůselnou hodnotu s limitem počtu 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í Azure Files.
`x-ms-recursive`	Nepovinný parametr. Logická hodnota, která určuje, jestli se má operace použít také na soubory a podadresáře adresáře zadaného v identifikátoru URI.
`x-ms-file-request-intent`	Vyžaduje se, pokud `Authorization` hlavička určuje token OAuth. Přijatelná hodnota je `backup`. Tato hlavička určuje, že `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` by se měly udělit nebo `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` , pokud jsou zahrnuté v zásadách RBAC přiřazené identitě, která je autorizována pomocí hlavičky `Authorization` . K dispozici pro verzi 2022-11-02 a novější.
`x-ms-allow-trailing-dot: { <Boolean> }`	Nepovinný parametr. Verze 2022-11-02 a novější. Logická hodnota určuje, jestli se má koncový tečka v adrese URL požadavku oříznout, nebo ne. Další informace najdete v tématu Pojmenování sdílených složek, adresářů, souborů a metadat a odkazování na nich.

Text požadavku

Žádné

Odpověď

Odpověď obsahuje stavový kód HTTP, sadu hlaviček odpovědi 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 najdete v tématu Stavové kódy a kódy chyb.

Hlavičky odpovědi

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

Hlavička odpovědi	Description
`Content-Type`	Určuje formát, ve kterém jsou výsledky vráceny. V současné době je `application/xml`tato hodnota .
`x-ms-request-id`	Tato hlavička jednoznačně identifikuje požadavek, který byl proveden, a lze ji 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 Azure Files použité ke spuštění požadavku.
`Date`	Hodnota data a času UTC, která označuje čas, kdy byla odpověď zahájena. Tato služba vygeneruje tuto hodnotu.
`x-ms-client-request-id`	Tuto hlavičku můžete použít k řešení potíží s požadavky a odpovídajícími odpověďmi. Hodnota této hlavičky se rovná hodnotě `x-ms-client-request-id` hlavičky, pokud se nachází v požadavku. Hodnota je maximálně 1024 viditelných znaků ASCII. Pokud se hlavička `x-ms-client-request-id` v požadavku nenachází, nebude tato hlavička v odpovědi.

Text odpovědi

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

<?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>
            <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	Description	Účel
`HandleId`	ID popisovače služby XSMB, UINT64.	Slouží 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 popisovač unikl.
`OpenTime`	Popisovač času byl otevřen (UTC). `DateTime` jako Řetězec.	Používá se k rozhodnutí, jestli popisovač neteče. Uniklé popisovače jsou obvykle otevřené po dlouhou dobu.
`LastReconnectTime`	Popisovač času byl otevřen (UTC). `DateTime` jako Řetězec.	Slouží 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 v textu odpovědi zahrnuto pouze v případě, že došlo k události odpojení a popisovač byl znovu otevřen.
`FileId`	ID souboru, UINT64.	`FileId` jedinečně identifikuje soubor. Je to užitečné při přejmenování, protože se `FileId` nemění.
`ParentId`	ID nadřazeného souboru, UINT64.	`ParentId` jedinečně identifikuje adresář. To je užitečné při přejmenování, protože se `ParentId` nemění.
`SessionId`	ID relace SMB, které určuje kontext, ve kterém byl popisovač souboru otevřen. 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 uniklý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 služby 2023-01-03 a novější. Používá se k dotazování přístupových oprávnění uložených 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ý má být uveden. Vrátí se, když je potřeba uvést více popisovačů, aby bylo možné požadavek dokončit.	Řetězec se používá v následných požadavcích k výpisu zbývajících popisovačů. Absence znamená `NextMarker` , že byly uvedeny všechny relevantní popisovače.

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

Autorizace

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

Poznámky

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