Freigeben über


Listenhandles

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 Ja
NFS Keine

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.

Siehe auch