Listenhandles

Artikel
02/21/2025

Der vorgang List Handles gibt eine Liste der geöffneten Handles in einem Verzeichnis oder einer 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

Bitten

Die List Handles Anforderung wird wie folgt erstellt. Es wird empfohlen, HTTPS zu verwenden.

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

Ersetzen Sie die pfadkomponenten, die im Anforderungs-URI angezeigt werden, wie folgt:

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

Ausführliche Informationen zu Pfadbenennungseinschränkungen 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`	Wahlfrei. Ein Zeichenfolgenwert, der den Teil der Liste identifiziert, der mit dem nächsten `List Handles` Vorgang zurückgegeben werden soll. Der Vorgang gibt einen Markierungswert im Antworttext zurück, wenn die zurückgegebene Liste nicht abgeschlossen wurde. Anschließend können Sie den Markierungswert in einem nachfolgenden Aufruf verwenden, um den nächsten Satz von Listenelementen anzufordern. Der Markerwert ist für den Client nicht transparent.
`maxresults`	Wahlfrei. Gibt die maximale Anzahl von Handles an, die für Dateien oder Verzeichnisse verwendet werden, die zurückgegeben werden sollen. Das Festlegen `maxresults` auf einen Wert kleiner oder gleich Null führt zu Fehlerantwortcode 400 (ungültige Anforderung).
`timeout`	Wahlfrei. Der parameter `timeout` wird in Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files-Vorgänge.
`sharesnapshot`	Wahlfrei. Der `sharesnapshot`-Parameter ist ein undurchsichtiger `DateTime` Wert, der, wenn vorhanden, die Freigabemomentaufnahme angibt, um die Liste der Handles abzufragen.

Anforderungsheader

In der folgenden Tabelle werden die erforderlichen und optionalen 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 (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 Vorgangs an, der für diese Anforderung verwendet werden soll. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage-Dienste.
`x-ms-client-request-id`	Wahlfrei. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem 1-Kibibyte-Zeichenlimit (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 von Azure Files.
`x-ms-recursive`	Wahlfrei. Ein boolescher Wert, der angibt, ob der Vorgang auch auf die Dateien und Unterverzeichnisse des im URI angegebenen Verzeichnisses angewendet werden soll.
`x-ms-file-request-intent`	Erforderlich, wenn `Authorization` Header ein OAuth-Token angibt. Zulässiger Wert ist `backup`. Dieser Header gibt an, dass die `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` oder `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` gewährt werden sollen, 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> }`	Wahlfrei. 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

Nichts.

Antwort

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

Statuscode

Ein erfolgreicher Vorgang gibt den Statuscode 200 (OK) zurück. Informationen zu Statuscodes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang enthält die Kopfzeilen in der folgenden Tabelle. Die Antwort kann auch zusätzliche Standard-HTTP-Header enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Allgemeine Kopfzeilen

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 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 die Uhrzeit angibt, zu der die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
`x-ms-client-request-id`	Sie können diesen Header verwenden, um Anfragen und entsprechende Antworten zu behandeln. 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

Das Format der XML-Antwort lautet wie folgt. Beachten Sie, dass die elemente Marker, ShareSnapshotund MaxResults nur vorhanden sind, wenn Sie sie für den Anforderungs-URI angegeben haben. Das NextMarker-Element weist nur dann einen Wert auf, wenn die Listenergebnisse nicht abgeschlossen sind.

ClientName Feld als Antwort ist optional und wird nur zurückgegeben, wenn er für den Dienst verfügbar ist.

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

Feld	Beschreibung	Zweck
`HandleId`	XSMB-Diensthandle ID, UINT64.	Wird zum Identifizieren des Handles verwendet.
`Path`	Dateiname, einschließlich des vollständigen Pfads, beginnend mit dem Freigabestamm. Schnur.	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. Schnur.	Wird verwendet, um zu entscheiden, ob der Griff möglicherweise verloren gegangen ist.
`ClientName`	Optionales Feld. Unterstützt in 2024-02-04 und höher. Clientname (Arbeitsstation oder Betriebssystembenutzername), der das Handle geöffnet hat. Schnur.	Wird verwendet, um zu entscheiden, ob der Griff möglicherweise verloren gegangen ist.
`OpenTime`	Zeitziehpunkt wurde geöffnet (UTC). `DateTime` als Zeichenfolge.	Wird verwendet, um zu entscheiden, ob der Handle möglicherweise verloren gegangen ist. Leckige Ziehpunkte sind in der Regel lange geöffnet.
`LastReconnectTime`	Zeitziehpunkt wurde geöffnet (UTC). `DateTime` als Zeichenfolge.	Wird verwendet, um zu entscheiden, ob das Handle aufgrund von Netzwerk- oder anderen Fehlern erneut geöffnet wurde, nachdem eine Client-/Serververbindung getrennt wurde. Das Feld ist nur dann im Antworttext enthalten, wenn das Disconnect-Ereignis aufgetreten ist und das Handle erneut geöffnet wurde.
`FileId`	Datei-ID, UINT64.	`FileId` identifiziert die Datei eindeutig. Es ist nützlich, während der Umbenennungen, da sich die `FileId` nicht ändert.
`ParentId`	Übergeordnete Datei-ID, UINT64.	`ParentId` identifiziert das Verzeichnis eindeutig. Dies ist bei Umbenennungen nützlich, da sich der `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 nicht getrennt werden. Damit können Sie einem bestimmten Netzwerkvorfall einen bestimmten Stapel von durchleckten Handles zuordnen.
`AccessRightList`	Die Zugriffsberechtigungen, die dem geöffneten Handle für Die Datei oder das Verzeichnis gewährt wurden.	Verfügbar in Service Version 2023-01-03 und höher. Wird verwendet, um Zugriffsberechtigungen abzufragen, die in einer Datei oder einem Verzeichnis von verschiedenen geöffneten Handles gespeichert sind. Mögliche Werte sind READ, WRITE und DELETE oder eine Kombination dieser Werte.
`NextMarker`	Eine Zeichenfolge, die das nächste Handle beschreibt, das aufgelistet werden soll. Sie wird zurückgegeben, wenn weitere Handles aufgelistet werden müssen, um die Anforderung abzuschließen.	Die Zeichenfolge wird in nachfolgenden Anforderungen zum Auflisten verbleibender Handles verwendet. Das Fehlen von `NextMarker` weist darauf hin, dass alle relevanten Handles aufgelistet wurden.

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

ClientName wird in Version 2024-02-04 und höher unterstützt.

Ermächtigung

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Bemerkungen

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

Freigeben über