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čů 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 Ano
NFS No

Žá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/xmltato 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.

Viz také