Lijstgrepen

Artikel
03/29/2023

De List Handles bewerking retourneert een lijst met geopende ingangen in een map of een bestand. Optioneel kan het recursief geopende ingangen in mappen en bestanden opsommen. Deze API is beschikbaar vanaf versie 2018-11-09.

Protocol beschikbaarheid

Bestandsshareprotocol ingeschakeld	Beschikbaar
SMB
NFS

Aanvraag

U kunt de List Handles aanvraag als volgt samenstellen. HTTPS wordt aanbevolen.

Methode	Aanvraag-URI	HTTP-versie
`GET`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles`	HTTP/1.1

Vervang de padonderdelen die worden weergegeven in de aanvraag-URI door uw eigen, als volgt:

Padonderdeel	Description
`myaccount`	De naam van uw opslagaccount.
`myshare`	De naam van uw bestandsshare.
`mydirectorypath`	Optioneel. Het pad naar de map.
`myfileordirectory`	De naam van het bestand of de map.

Zie Naamgeving en verwijzingen naar shares, mappen, bestanden en metagegevens voor meer informatie over padnaambeperkingen.

URI-parameters

U kunt de volgende aanvullende parameters opgeven voor de URI.

Parameter	Beschrijving
`marker`	Optioneel. Een tekenreekswaarde die het deel van de lijst aangeeft dat bij de volgende `List Handles` bewerking moet worden geretourneerd. De bewerking retourneert een markeringswaarde in de hoofdtekst van het antwoord, als de geretourneerde lijst niet voltooid is. Vervolgens kunt u de markeringswaarde in een volgende aanroep gebruiken om de volgende set lijstitems aan te vragen. De markeringswaarde is ondoorzichtig voor de client.
`maxresults`	Optioneel. Hiermee geeft u het maximum aantal ingangen op dat moet worden gebruikt voor bestanden of mappen die moeten worden geretourneerd. Als u instelt `maxresults` op een waarde die kleiner is dan of gelijk is aan nul, resulteert dit in foutcode 400 (ongeldige aanvraag).
`timeout`	Optioneel. De `timeout` parameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Azure Files bewerkingen voor meer informatie.
`sharesnapshot`	Optioneel. De `sharesnapshot` parameter is een ondoorzichtige `DateTime` waarde die, indien aanwezig, de momentopname van de share opgeeft die moet worden opgevraagd voor de lijst met ingangen.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven.

Aanvraagheader	Beschrijving
`Authorization`	Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening op. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
`Date` of `x-ms-date`	Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
`x-ms-version`	Vereist voor alle geautoriseerde aanvragen, optioneel voor anonieme aanvragen. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
`x-ms-client-request-id`	Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Azure Files bewaken voor meer informatie.
`x-ms-recursive`	Optioneel. Een Booleaanse waarde die aangeeft of de bewerking ook van toepassing moet zijn op de bestanden en submappen van de map die is opgegeven in de URI.
`x-ms-file-request-intent`	Vereist als `Authorization` header een OAuth-token opgeeft. Acceptabele waarde is `backup`. Deze header geeft aan dat de `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` of `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` moet worden verleend als deze zijn opgenomen in het RBAC-beleid dat is toegewezen aan de identiteit die is geautoriseerd met behulp van de `Authorization` header. Beschikbaar voor versie 2022-11-02 en hoger.
`x-ms-allow-trailing-dot: { <Boolean> }`	Optioneel. Versie 2022-11-02 en hoger. De Booleaanse waarde geeft aan of een afsluitende punt die aanwezig is in de aanvraag-URL moet worden ingekort of niet. Zie Naamgeving en verwijzingen naar shares, mappen, bestanden en metagegevens voor meer informatie.

Aanvraagbody

Geen.

Antwoord

Het antwoord bevat een HTTP-statuscode, een set antwoordheaders en een antwoordtekst in XML-indeling.

Statuscode

Een geslaagde bewerking retourneert statuscode 200 (OK). Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

Het antwoord voor deze bewerking bevat de volgende headers. Het antwoord kan ook extra, standaard HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Antwoordheader	Description
`Content-Type`	Hiermee geeft u de indeling op waarin de resultaten worden geretourneerd. Momenteel is `application/xml`deze waarde .
`x-ms-request-id`	Deze header identificeert op unieke wijze de aanvraag die is gedaan en kan worden gebruikt voor het oplossen van problemen met de aanvraag. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
`x-ms-version`	Geeft de versie aan van Azure Files gebruikt om de aanvraag uit te voeren.
`Date`	Een UTC-datum/tijd-waarde die de tijd aangeeft waarop het antwoord is gestart. De service genereert deze waarde.
`x-ms-client-request-id`	U kunt deze header gebruiken om problemen met aanvragen en bijbehorende antwoorden op te lossen. De waarde van deze header is gelijk aan de waarde van de `x-ms-client-request-id` header, als deze aanwezig is in de aanvraag. De waarde is maximaal 1024 zichtbare ASCII-tekens. Als de `x-ms-client-request-id` header niet aanwezig is in de aanvraag, is deze header niet aanwezig in het antwoord.

Hoofdtekst van de reactie

De indeling van het XML-antwoord is als volgt. Houd er rekening mee dat de Markerelementen , ShareSnapshoten MaxResults alleen aanwezig zijn als u deze hebt opgegeven in de aanvraag-URI. Het NextMarker element heeft alleen een waarde als de lijstresultaten niet volledig zijn.

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

In de volgende tabel worden de velden van de hoofdtekst van het antwoord beschreven:

Veld	Description	Doel
`HandleId`	ID van XSMB-servicehandgreep, UINT64.	Wordt gebruikt om ingang te identificeren.
`Path`	Bestandsnaam, inclusief het volledige pad, beginnend bij de hoofdmap van de share. Tekenreeks.	Wordt gebruikt om de naam te identificeren van het object waarvoor de ingang is geopend.
`ClientIp`	Client-IP die de ingang heeft geopend. Tekenreeks.	Wordt gebruikt om te bepalen of de greep mogelijk is gelekt.
`OpenTime`	De tijdgreep is geopend (UTC). `DateTime` als Tekenreeks.	Wordt gebruikt om te bepalen of de ingang mogelijk is gelekt. Gelekte ingangen zijn doorgaans al lange tijd open.
`LastReconnectTime`	De tijdgreep is geopend (UTC). `DateTime` als Tekenreeks.	Wordt gebruikt om te bepalen of de ingang opnieuw is geopend nadat de client/server is verbroken, vanwege netwerkfouten of andere fouten. Het veld wordt alleen opgenomen in de hoofdtekst van het antwoord als de verbinding is verbroken en de ingang opnieuw is geopend.
`FileId`	Bestands-id, UINT64.	`FileId` identificeert het bestand uniek. Het is handig bij het wijzigen van namen, omdat de `FileId` niet verandert.
`ParentId`	Bovenliggende bestands-id, UINT64.	`ParentId` identificeert de map op unieke wijze. Dit is handig bij het wijzigen van namen, omdat de `ParentId` niet verandert.
`SessionId`	SMB-sessie-id die de context aangeeft waarin de bestandsingang is geopend. UINT64.	`SessionId` is opgenomen in logboeken wanneer sessies geforceerd worden verbroken. Hiermee kunt u een specifieke batch gelekte ingangen koppelen aan een specifiek netwerkincident.
`AccessRightList`	De toegangsmachtigingen die worden verleend aan de open ingang voor het bestand of de map.	Beschikbaar in serviceversie 2023-01-03 en hoger. Wordt gebruikt voor het opvragen van toegangsmachtigingen voor een bestand of map door verschillende geopende ingangen. Mogelijke waarden zijn LEZEN, SCHRIJVEN en VERWIJDEREN, of een combinatie van deze waarden.
`NextMarker`	Een tekenreeks die de volgende ingang beschrijft die moet worden weergegeven. Deze wordt geretourneerd wanneer er meer ingangen moeten worden vermeld om de aanvraag te voltooien.	De tekenreeks wordt gebruikt in volgende aanvragen om de resterende ingangen weer te geven. De afwezigheid van `NextMarker` geeft aan dat alle relevante ingangen zijn vermeld.

In versies 2021-12-02 en hoger worden List Handles alle Path elementwaarden die ongeldig zijn in XML (met name U+FFFE of U+FFFFFF) procentgecodeerd (per RFC 2396). Indien gecodeerd, bevat het Path element een Encoded=true kenmerk. Houd er rekening mee dat dit alleen gebeurt voor de Path elementwaarden die de tekens bevatten die ongeldig zijn in XML, niet voor de resterende Path elementen in het antwoord.

Autorisatie

Alleen de accounteigenaar kan deze bewerking aanroepen.

Opmerkingen

De HandleId is een ingangs-id aan de servicezijde, die verschilt van de clienthandgreep-id. Toewijzing tussen de twee is mogelijk bij de client.