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 |
![]() |
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
, ShareSnapshot
a 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