Listreferenser

Artikel
02/19/2025

Åtgärden List Handles returnerar en lista över öppna referenser i en katalog eller en fil. Alternativt kan den rekursivt räkna upp öppnade referenser på kataloger och filer. Det här API:et är tillgängligt från och med version 2018-11-09.

Protokolltillgänglighet

Aktiverat filresursprotokoll	Tillgänglig
SMB
NFS

Begäran

Den List Handles begäran skapas på följande sätt. Vi rekommenderar att du använder HTTPS.

Metod	Begärande-URI	HTTP-version
FÅ	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles`	HTTP/1.1

Ersätt sökvägskomponenterna som visas i begärande-URI:n med dina egna enligt följande:

Sökvägskomponent	Beskrivning
`myaccount`	Namnet på ditt lagringskonto.
`myshare`	Namnet på filresursen.
`mydirectorypath`	Valfri. Sökvägen till katalogen.
`myfileordirectory`	Namnet på filen eller katalogen.

Mer information om namngivningsbegränsningar för sökvägar finns i Namngivnings- och referensresurser, kataloger, filer och metadata.

URI-parametrar

Du kan ange följande ytterligare parametrar på URI:n.

Parameter	Beskrivning
`marker`	Valfri. Ett strängvärde som identifierar den del av listan som ska returneras med nästa `List Handles` åtgärd. Åtgärden returnerar ett markörvärde i svarstexten om listan som returnerades inte slutfördes. Du kan sedan använda markörvärdet i ett efterföljande anrop för att begära nästa uppsättning listobjekt. Markörvärdet är ogenomskinlig för klienten.
`maxresults`	Valfri. Anger det maximala antalet handtag som tas på filer eller kataloger som ska returneras. Om du anger `maxresults` till ett värde som är mindre än eller lika med noll resulterar det i felsvarskoden 400 (felaktig begäran).
`timeout`	Valfri. Parametern `timeout` uttrycks i sekunder. Mer information finns i Ange tidsgränser för Azure Files-åtgärder.
`sharesnapshot`	Valfri. Parametern `sharesnapshot` är en ogenomskinlig `DateTime` värde som, när den finns, anger resursögonblicksbilden för att fråga efter listan över referenser.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria begärandehuvuden.

Begärandehuvud	Beskrivning
`Authorization`	Krävs. Anger auktoriseringsschema, kontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage.
`Date` eller `x-ms-date`	Krävs. Anger UTC (Coordinated Universal Time) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
`x-ms-version`	Krävs för alla auktoriserade begäranden, valfritt för anonyma begäranden. Anger vilken version av åtgärden som ska användas för den här begäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
`x-ms-client-request-id`	Valfri. Tillhandahåller ett klientgenererat, täckande värde med en kibibytesteckengräns (KiB) som registreras i loggarna när loggningen konfigureras. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot. Mer information finns i Övervaka Azure Files-.
`x-ms-recursive`	Valfri. Ett booleskt värde som anger om åtgärden också ska gälla för filerna och underkatalogerna i katalogen som anges i URI:n.
`x-ms-file-request-intent`	Krävs om `Authorization` rubrik anger en OAuth-token. Acceptabelt värde är `backup`. Det här huvudet anger att `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` eller `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` ska beviljas om de ingår i RBAC-principen som tilldelats den identitet som är auktoriserad med hjälp av `Authorization`-huvudet. Tillgänglig för version 2022-11-02 och senare.
`x-ms-allow-trailing-dot: { <Boolean> }`	Valfri. Version 2022-11-02 och senare. Det booleska värdet anger om en avslutande punkt som finns i begärande-URL:en ska trimmas eller inte. Mer information finns i Namngivning och referens av resurser, kataloger, filer och metadata.

Begärandetext

Ingen.

Svar

Svaret innehåller en HTTP-statuskod, en uppsättning svarshuvuden och en svarstext i XML-format.

Statuskod

En lyckad åtgärd returnerar statuskod 200 (OK). Information om statuskoder finns i Status och felkoder.

Svarshuvuden

Svaret för den här åtgärden innehåller rubrikerna i följande tabell. Svaret kan också innehålla ytterligare standard-HTTP-huvuden. Alla standardhuvuden överensstämmer med HTTP/1.1-protokollspecifikationen.

Vanliga rubriker

Svarsrubrik	Beskrivning
`Content-Type`	Anger i vilket format resultatet returneras. För närvarande är det här värdet `application/xml`.
`x-ms-request-id`	Det här huvudet identifierar unikt den begäran som gjordes och kan användas för att felsöka begäran. Mer information finns i Felsökning av API-åtgärder.
`x-ms-version`	Anger vilken version av Azure Files som används för att köra begäran.
`Date`	Ett UTC-datum/tid-värde som anger den tid då svaret initierades. Tjänsten genererar det här värdet.
`x-ms-client-request-id`	Du kan använda den här rubriken för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet för `x-ms-client-request-id`-huvudet, om det finns i begäran. Värdet är högst 1 024 synliga ASCII-tecken. Om `x-ms-client-request-id`-huvudet inte finns i begäran visas inte det här huvudet i svaret.

Svarstext

Formatet för XML-svaret är följande. Observera att elementen Marker, ShareSnapshotoch MaxResults endast finns om du har angett dem på begärande-URI:n. Elementet NextMarker har bara ett värde om listresultatet inte är slutfört.

ClientName fält som svar är valfritt och returneras endast när det är tillgängligt för tjänsten.

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

I följande tabell beskrivs fälten i svarstexten:

Fält	Beskrivning	Avsikt
`HandleId`	XSMB-tjänsten hanterar ID, UINT64.	Används för att identifiera handtag.
`Path`	Filnamn, inklusive den fullständiga sökvägen, med början från resursroten. Sträng.	Används för att identifiera namnet på det objekt som handtaget är öppet för.
`ClientIp`	Klient-IP som öppnade handtaget. Sträng.	Används för att avgöra om handtaget kan ha läckt ut.
`ClientName`	Valfritt fält. Stöds 2024-02-04 och senare. Klientnamn (arbetsstation eller operativsystemanvändarnamn) som öppnade handtaget. Sträng.	Används för att avgöra om handtaget kan ha läckt ut.
`OpenTime`	Tidshandtaget öppnades (UTC). `DateTime` som Sträng.	Används för att avgöra om handtaget kan ha läckt ut. Läckta handtag har vanligtvis varit öppna under lång tid.
`LastReconnectTime`	Tidshandtaget öppnades (UTC). `DateTime` som Sträng.	Används för att avgöra om handtaget öppnades igen efter att en klient/server har kopplats från på grund av nätverk eller andra fel. Fältet ingår endast i svarstexten om frånkopplingshändelsen inträffade och handtaget öppnades igen.
`FileId`	Fil-ID, UINT64.	`FileId` identifierar filen unikt. Det är användbart när du byter namn eftersom `FileId` inte ändras.
`ParentId`	Överordnat fil-ID, UINT64.	`ParentId` identifierar katalogen unikt. Detta är användbart när du byter namn eftersom `ParentId` inte ändras.
`SessionId`	SMB-sessions-ID som anger i vilken kontext filhandtaget öppnades. UINT64.	`SessionId` ingår i loggbokens loggar när sessioner kopplas från med två skäl. Det gör att du kan associera en specifik batch med läckta handtag med en specifik nätverksincident.
`AccessRightList`	Åtkomstbehörigheterna som beviljats till det öppna handtaget för filen eller katalogen.	Finns i tjänstversion 2023-01-03 och senare. Används för att fråga åtkomstbehörigheter som finns i en fil eller katalog med olika öppna referenser. Möjliga värden är READ, WRITE och DELETE eller en kombination av dessa värden.
`NextMarker`	En sträng som beskriver nästa handtag som ska visas. Den returneras när fler handtag behöver anges för att slutföra begäran.	Strängen används i efterföljande begäranden för att lista återstående handtag. Avsaknaden av `NextMarker` anger att alla relevanta referenser har listats.

I versionerna 2021-12-02 och senare kommer List Handles procentkoda (per RFC 2396) alla Path elementvärden som innehåller tecken som är ogiltiga i XML (specifikt U+FFFE eller U+FFFF). Om det kodas innehåller elementet Path ett Encoded=true attribut. Observera att detta endast inträffar för de Path elementvärden som innehåller tecknen som är ogiltiga i XML, inte de återstående Path elementen i svaret.

ClientName stöds i version 2024-02-04 och senare.

Tillstånd

Endast kontoägaren kan anropa den här åtgärden.

Anmärkningar

HandleId är ett handtags-ID på tjänstsidan, som skiljer sig från klienthandtags-ID:t. Det går att mappa mellan de två på klienten.

Dela via