Listenhandles

Artikel
03/29/2023

Der List Handles Vorgang gibt eine Liste geöffneter Handles für ein Verzeichnis oder eine Datei zurück. Optional können geöffnete Handles in Verzeichnissen und Dateien rekursiv aufgezählt werden. Diese API ist ab Version 2018-11-09 verfügbar.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll	Verfügbar
SMB
NFS

Anforderung

Sie können die List Handles Anforderung wie folgt erstellen. HTTPS wird empfohlen.

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

Ersetzen Sie die im Anforderungs-URI angezeigten Pfadkomponenten wie folgt durch Ihre eigenen Angaben:

Pfadkomponente	BESCHREIBUNG
`myaccount`	Der Name Ihres Speicherkontos.
`myshare`	Der Name der Dateifreigabe.
`mydirectorypath`	Optional. Der Pfad zum Verzeichnis.
`myfileordirectory`	Der Name der Datei oder des Verzeichnisses.

Ausführliche Informationen zu Einschränkungen bei der Pfadbenennung finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

URI-Parameter

Sie können die folgenden zusätzlichen Parameter für den URI angeben.

Parameter	BESCHREIBUNG
`marker`	Optional. Ein Zeichenfolgenwert, der den Teil der Liste angibt, der beim nächsten `List Handles` Vorgang zurückgegeben werden soll. Der Vorgang gibt einen Markerwert innerhalb des Antworttexts zurück, wenn die zurückgegebene Liste nicht vollständig war. Sie können dann den Markerwert in einem nachfolgenden Aufruf verwenden, um den nächsten Satz von Listenelementen anzufordern. Der Markerwert ist für den Client nicht transparent.
`maxresults`	Optional. Gibt die maximale Anzahl von Handles an, die für Dateien oder Verzeichnisse verwendet werden, die zurückgegeben werden sollen. Wenn `maxresults` auf einen Wert kleiner oder gleich 0 festgelegt ist, wird Fehlerantwortcode 400 ausgegeben (ungültige Anforderung).
`timeout`	Optional. Der `timeout`-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files Vorgänge.
`sharesnapshot`	Optional. Der `sharesnapshot` Parameter ist ein undurchsichtiger `DateTime` Wert, der, sofern vorhanden, die Freigabe Momentaufnahme angibt, die nach der Liste der Handles abzufragen ist.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

Anforderungsheader	BESCHREIBUNG
`Authorization`	Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`Date` oder `x-ms-date`	Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`x-ms-version`	Erforderlich für alle autorisierten Anforderungen, optional für anonyme Anforderungen. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
`x-ms-client-request-id`	Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen Azure Files.
`x-ms-recursive`	Optional. Ein boolescher Wert, der angibt, ob der Vorgang auch für die Dateien und Unterverzeichnisse des im URI angegebenen Verzeichnisses gelten soll.
`x-ms-file-request-intent`	Erforderlich, wenn `Authorization` der Header ein OAuth-Token angibt. Zulässiger Wert ist `backup`. Dieser Header gibt an, dass oder `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` gewährt werden soll, wenn sie in der RBAC-Richtlinie enthalten sind, die der Identität zugewiesen ist, die mithilfe des `Authorization` Headers autorisiert ist. Verfügbar für Version 2022-11-02 und höher.
`x-ms-allow-trailing-dot: { <Boolean> }`	Optional. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein nachgestellter Punkt in der Anforderungs-URL gekürzt werden soll. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

Anforderungstext

Keine

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern und einen Antworttext im XML-Format.

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 200 (OK) zurückgegeben. Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann auch zusätzliche HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader	BESCHREIBUNG
`Content-Type`	Gibt das Format an, in dem die Ergebnisse zurückgegeben werden. Derzeit ist dieser Wert `application/xml`.
`x-ms-request-id`	Dieser Header identifiziert die durchgeführte Anforderung eindeutig und kann für die Problembehandlung der Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
`x-ms-version`	Gibt die Version von Azure Files an, die zum Ausführen der Anforderung verwendet wird.
`Date`	Ein UTC-Datums-/Uhrzeitwert, der den Zeitpunkt angibt, zu dem die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
`x-ms-client-request-id`	Sie können diesen Header verwenden, um Probleme mit Anforderungen und entsprechenden Antworten zu beheben. Der Wert dieses Headers ist gleich dem Wert des `x-ms-client-request-id` Headers, wenn er in der Anforderung vorhanden ist. Der Wert beträgt höchstens 1024 sichtbare ASCII-Zeichen. Wenn der `x-ms-client-request-id` Header in der Anforderung nicht vorhanden ist, ist dieser Header in der Antwort nicht vorhanden.

Antworttext

Die XML-Antwort weist das folgende Format auf: Beachten Sie, dass die MarkerElemente , ShareSnapshotund MaxResults nur vorhanden sind, wenn Sie sie im Anforderungs-URI angegeben haben. Das NextMarker -Element hat nur dann einen Wert, wenn die Listenergebnisse nicht vollständig sind.

<?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 der folgenden Tabelle werden die Felder des Antworttexts beschrieben:

Feld	BESCHREIBUNG	Zweck
`HandleId`	XSMB-Diensthandle-ID, UINT64.	Wird verwendet, um das Handle zu identifizieren.
`Path`	Dateiname, einschließlich des vollständigen Pfads, beginnend mit dem Freigabestamm. Eine Zeichenfolge.	Wird verwendet, um den Namen des Objekts zu identifizieren, für das das Handle geöffnet ist.
`ClientIp`	Client-IP, die das Handle geöffnet hat. Eine Zeichenfolge.	Wird verwendet, um zu entscheiden, ob das Handle möglicherweise kompromittiert wurde.
`OpenTime`	Zeithandle wurde geöffnet (UTC). `DateTime` als Zeichenfolge.	Wird verwendet, um zu entscheiden, ob das Handle möglicherweise kompromittiert wurde. Kompromittierte Handles sind in der Regel schon lange geöffnet.
`LastReconnectTime`	Zeithandle wurde geöffnet (UTC). `DateTime` als Zeichenfolge.	Wird verwendet, um zu entscheiden, ob das Handle erneut geöffnet wurde, nachdem eine Client/Server-Verbindung aufgrund von Netzwerk- oder anderen Fehlern getrennt wurde. Das Feld ist nur dann im Antworttext enthalten, wenn das Trennungsereignis aufgetreten ist und das Handle erneut geöffnet wurde.
`FileId`	Datei-ID, UINT64.	`FileId` identifiziert die Datei eindeutig. Es ist bei Umbenennungen nützlich, da sich die `FileId` nicht ändert.
`ParentId`	Übergeordnete Datei-ID, UINT64.	`ParentId` identifiziert das Verzeichnis eindeutig. Dies ist bei Umbenennungen nützlich, da sich die `ParentId` nicht ändert.
`SessionId`	SMB-Sitzungs-ID, die den Kontext angibt, in dem das Dateihandle geöffnet wurde. UINT64.	`SessionId` ist in Ereignisanzeigeprotokollen enthalten, wenn Sitzungen erzwungen getrennt werden. Sie ermöglicht es Ihnen, einen bestimmten Batch von kompromittierten Handles einem bestimmten Netzwerkvorfall zuzuordnen.
`AccessRightList`	Die Zugriffsberechtigungen, die dem geöffneten Handle für die Datei oder das Verzeichnis gewährt werden.	Verfügbar in Dienstversion 2023-01-03 und höher. Wird verwendet, um Zugriffsberechtigungen abzufragen, die von verschiedenen geöffneten Handles für eine Datei oder ein Verzeichnis gespeichert werden. Mögliche Werte sind READ, WRITE und DELETE oder eine Kombination dieser Werte.
`NextMarker`	Eine Zeichenfolge, die das nächste aufgelistete Handle beschreibt. Es wird zurückgegeben, wenn weitere Handles aufgelistet werden müssen, um die Anforderung abzuschließen.	Die Zeichenfolge wird in nachfolgenden Anforderungen verwendet, um die verbleibenden Handles auflisten. Das Fehlen von `NextMarker` gibt an, dass alle relevanten Handles aufgelistet wurden.

In den Versionen 2021-12-02 und höher werden alle Path Elementwerte prozentual List Handles codiert (gemäß RFC 2396), die ungültige Zeichen in XML enthalten (insbesondere U+FFFE oder U+FFFF). Wenn es codiert ist, enthält das Path Element ein Encoded=true Attribut. Beachten Sie, dass dies nur für die Path Elementwerte auftritt, die die in XML ungültigen Zeichen enthalten, nicht für die verbleibenden Path Elemente in der Antwort.

Autorisierung

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Bemerkungen

Ist HandleId eine dienstseitige Handle-ID, die sich von der Clienthandle-ID unterscheidet. Die Zuordnung zwischen den beiden ist auf dem Client möglich.