Listreferenser

Artikel
03/29/2023

Åtgärden List Handles returnerar en lista över öppna referenser för 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ängligt
SMB
NFS

Förfrågan

Du kan skapa begäran på List Handles följande sätt. HTTPS rekommenderas.

Metod	URI för förfrågan	HTTP-version
`GET`	`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	Description
`myaccount`	Namnet på ditt lagringskonto.
`myshare`	Namnet på filresursen.
`mydirectorypath`	Valfritt. Sökvägen till katalogen.
`myfileordirectory`	Namnet på filen eller katalogen.

Mer information om namngivningsbegränsningar för sökvägar finns i Namnge och referera till resurser, kataloger, filer och metadata.

URI-parametrar

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

Parameter	Beskrivning
`marker`	Valfritt. 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 täckande för klienten.
`maxresults`	Valfritt. Anger det maximala antalet referenser som tas på filer eller kataloger som ska returneras. Om du anger `maxresults` ett värde som är mindre än eller lika med noll returneras felsvarskoden 400 (felaktig begäran).
`timeout`	Valfritt. Parametern `timeout` uttrycks i sekunder. Mer information finns i Ställa in tidsgränser för Azure Files åtgärder.
`sharesnapshot`	Valfritt. Parametern `sharesnapshot` är ett täckande `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 Coordinated Universal Time (UTC) 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`	Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggning har konfigurerats. 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`	Valfritt. 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` huvudet 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 DEN RBAC-princip som tilldelats den identitet som har behörighet med hjälp av `Authorization` huvudet. Tillgänglig för version 2022-11-02 och senare.
`x-ms-allow-trailing-dot: { <Boolean> }`	Valfritt. 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 Namnge och referera till resurser, kataloger, filer och metadata.

Begärandetext

Inga.

Svarsåtgärder

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 följande rubriker. Svaret kan även innehålla ytterligare STANDARD HTTP-huvuden. Alla standardhuvuden överensstämmer med http/1.1-protokollspecifikationen.

Svarsrubrik	Description
`Content-Type`	Anger i vilket format resultaten returneras. För närvarande är `application/xml`det här värdet .
`x-ms-request-id`	Det här huvudet identifierar unikt den begäran som har gjorts och kan användas för att felsöka begäran. Mer information finns i Felsöka API-åtgärder.
`x-ms-version`	Anger vilken version av Azure Files som används för att köra begäran.
`Date`	Ett datum-/tidsvärde för UTC som anger den tid då svaret initierades. Tjänsten genererar det här värdet.
`x-ms-client-request-id`	Du kan använda det här huvudet 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 rubriken `x-ms-client-request-id` inte finns i begäran kommer det här huvudet inte att finnas i svaret.

Själva svaret

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

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

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

Fält	Beskrivning	Syfte
`HandleId`	XSMB-tjänstreferens-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 referensen är öppen för.
`ClientIp`	Klient-IP 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 referensen 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 referensen öppnades igen efter en klient/server-frånkoppling på grund av nätverk eller andra fel. Fältet ingår bara i svarstexten om frånkopplingshändelsen inträffade och referensen öppnades igen.
`FileId`	Fil-ID, UINT64.	`FileId` identifierar filen unikt. Det är användbart under namnbyten, eftersom `FileId` inte ändras.
`ParentId`	Överordnat fil-ID, UINT64.	`ParentId` identifierar katalogen unikt. Detta är användbart under namnbyten, eftersom `ParentId` inte ändras.
`SessionId`	SMB-sessions-ID som anger i vilken kontext filreferensen öppnades. UINT64.	`SessionId` ingår i loggbokens loggar när sessioner med två två försök kopplas från. Det gör att du kan associera en specifik batch med läckta referenser med en specifik nätverksincident.
`AccessRightList`	De åtkomstbehörigheter som beviljats till det öppna handtaget för filen eller katalogen.	Tillgänglig 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 referens 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 visa återstående referenser. Avsaknaden av `NextMarker` anger att alla relevanta referenser har listats.

I version 2021-12-02 och senare kommer List Handles procentkoda (per RFC 2396) alla Path elementvärden som innehåller ogiltiga tecken 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.

Auktorisering

Endast kontoinnehavaren kan anropa den här åtgärden.

Kommentarer

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