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 |
![]() |
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
, ShareSnapshot
und 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.