Lijstgrepen

Artikel
02/21/2025

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

Beschikbaarheid van protocol

Protocol voor bestandsshare ingeschakeld	Beschikbaar
SMB
NFS

Verzoek

De List Handles aanvraag wordt als volgt samengesteld. U wordt aangeraden HTTPS te gebruiken.

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

Vervang de padonderdelen in de aanvraag-URI als volgt door uw eigen padonderdelen:

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

Zie Naamgeving en verwijzingen naar shares, mappen, bestanden en metagegevensvoor meer informatie over padnaamgevingsbeperkingen.

URI-parameters

U kunt de volgende aanvullende parameters voor de URI opgeven.

Parameter	Beschrijving
`marker`	Facultatief. Een tekenreekswaarde die het deel van de lijst aangeeft dat moet worden geretourneerd met de volgende `List Handles` bewerking. De bewerking retourneert een markeringswaarde in de hoofdtekst van het antwoord als de geretourneerde lijst niet is voltooid. 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`	Facultatief. Hiermee geeft u het maximum aantal ingangen op bestanden of mappen die moeten worden geretourneerd. Als u `maxresults` instelt op een waarde die kleiner is dan of gelijk is aan nul, resulteert dit in foutcode 400 (Ongeldige aanvraag).
`timeout`	Facultatief. De parameter `timeout` wordt uitgedrukt in seconden. Zie Time-outs instellen voor Azure Files-bewerkingenvoor meer informatie.
`sharesnapshot`	Facultatief. De parameter `sharesnapshot` is een ondoorzichtige `DateTime` waarde die, indien aanwezig, de momentopname van de share opgeeft waarop een query moet worden uitgevoerd voor de lijst met ingangen.

Aanvraagheaders

In de volgende tabel worden de 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 Storagevoor meer informatie.
`Date` of `x-ms-date`	Vereist. Hiermee geeft u de Coordinated Universal Time (UTC) voor de aanvraag. Zie Aanvragen autoriseren voor Azure Storagevoor meer informatie.
`x-ms-version`	Vereist voor alle geautoriseerde aanvragen, optioneel voor anonieme aanvragen. Hiermee geeft u de versie van de bewerking die moet worden gebruikt voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-servicesvoor meer informatie.
`x-ms-client-request-id`	Facultatief. Biedt een door de client gegenereerde, ondoorzichtige waarde met een tekenlimiet 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 Monitor Azure Filesvoor meer informatie.
`x-ms-recursive`	Facultatief. 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` moeten worden verleend als ze 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> }`	Facultatief. Versie 2022-11-02 en hoger. De Booleaanse waarde geeft aan of een volgpunt aanwezig in de aanvraag-URL moet worden ingekort of niet. Zie Shares, mappen, bestanden en metagegevensvoor 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 foutcodesvoor meer informatie over statuscodes.

Antwoordheaders

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

Algemene kopteksten

Antwoordheader	Beschrijving
`Content-Type`	Hiermee geeft u de indeling op waarin de resultaten worden geretourneerd. Deze waarde is momenteel `application/xml`.
`x-ms-request-id`	Deze header identificeert de aanvraag die is gemaakt en kan worden gebruikt voor het oplossen van problemen met de aanvraag. Zie Problemen met API-bewerkingen oplossenvoor meer informatie.
`x-ms-version`	Geeft de versie van Azure Files aan die wordt 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 antwoord

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

ClientName veld in antwoord is optioneel en wordt alleen geretourneerd wanneer het beschikbaar is voor de service.

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

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

Veld	Beschrijving	Doel
`HandleId`	XSMB-servicehandler-id, UINT64.	Wordt gebruikt om ingang te identificeren.
`Path`	Bestandsnaam, inclusief het volledige pad, beginnend vanaf de hoofdmap van de share. Snaar.	Wordt gebruikt om de naam te identificeren van het object waarvoor de ingang is geopend.
`ClientIp`	Client-IP waarmee de ingang is geopend. Snaar.	Wordt gebruikt om te bepalen of de greep mogelijk is gelekt.
`ClientName`	Optioneel veld. Ondersteund in 2024-02-04 en hoger. Clientnaam (werkstation of gebruikersnaam van besturingssysteem) waarmee de ingang is geopend. Snaar.	Wordt gebruikt om te bepalen of de greep mogelijk is gelekt.
`OpenTime`	Tijdgreep is geopend (UTC). `DateTime` als tekenreeks.	Wordt gebruikt om te bepalen of de ingang is gelekt. Gelekte ingangen zijn doorgaans al lange tijd open.
`LastReconnectTime`	Tijdgreep is geopend (UTC). `DateTime` als tekenreeks.	Wordt gebruikt om te bepalen of de ingang opnieuw is geopend nadat de verbinding met een client/server is verbroken vanwege netwerken of andere fouten. Het veld is alleen opgenomen in de hoofdtekst van het antwoord als de verbinding is verbroken en de ingang opnieuw is geopend.
`FileId`	Bestands-id, UINT64.	`FileId` het bestand uniek identificeert. Het is handig tijdens het wijzigen van de naam, omdat de `FileId` niet verandert.
`ParentId`	Bovenliggende bestands-id, UINT64.	`ParentId` de map uniek identificeert. Dit is handig tijdens het wijzigen van de naam, omdat de `ParentId` niet verandert.
`SessionId`	SMB-sessie-id die de context aangeeft waarin de bestandsingang is geopend. UINT64.	`SessionId` wordt opgenomen in logboeken van logboeken wanneer sessies geforceerd worden verbroken. Hiermee kunt u een specifieke batch gelekte ingangen koppelen aan een specifiek netwerkincident.
`AccessRightList`	De toegangsmachtigingen die zijn verleend aan de geopende ingang in een bestand of map.	Beschikbaar in serviceversie 2023-01-03 en hoger. Wordt gebruikt voor het opvragen van toegangsmachtigingen die zijn opgeslagen in een bestand of map door verschillende geopende ingangen. Mogelijke waarden zijn READ, WRITE en DELETE of een combinatie van deze waarden.
`NextMarker`	Een tekenreeks die de volgende ingang beschrijft die moet worden weergegeven. Het wordt geretourneerd wanneer er meer ingangen moeten worden vermeld om de aanvraag te voltooien.	De tekenreeks wordt gebruikt in volgende aanvragen om resterende ingangen weer te geven. Het ontbreken van `NextMarker` geeft aan dat alle relevante ingangen zijn vermeld.

In versies 2021-12-02 en hoger worden in List Handles procentcodering (per RFC 2396) alle Path elementwaarden die ongeldige tekens bevatten in XML (met name U+FFFE of U+FFFFFF). Als dit is 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 de resterende Path elementen in het antwoord.

ClientName wordt ondersteund in versie 2024-02-04 en hoger.

Machtiging

Alleen de accounteigenaar kan deze bewerking aanroepen.

Opmerkingen

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

Delen via