Bereiche auflisten

Der vorgang List Ranges gibt die Liste der gültigen Bereiche für eine Datei zurück. Dieser Vorgang wird in Version 2025-05-05 und höher für Dateifreigaben mit aktiviertem NFS-Protokoll unterstützt. Ab Version 2026-10-06 unterstützt diese Operation Fortsetzungstoken über die marker und-Parameter maxresults .

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll Verfügbar
SMB Ja
NFS Ja

Bitten

Die List Ranges 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/myfile?comp=rangelist HTTP/1.1
ERHALTEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&maxresults=<int> HTTP/1.1
ERHALTEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string>&maxresults=<int> HTTP/1.1
ERHALTEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string> HTTP/1.1
ERHALTEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist HTTP/1.1
ERHALTEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime> HTTP/1.1
ERHALTEN https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime> 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 übergeordneten Verzeichnis.
myfile Der Name der Datei.

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 Anforderungs-URI angeben.

Parameter Beschreibung
sharesnapshot Wahlfrei. Version 2017-04-17 und höher. Der sharesnapshot-Parameter ist ein undurchsichtiger DateTime Wert, der, wenn vorhanden, die Freigabemomentaufnahme angibt, um die Datei abzufragen.
timeout Wahlfrei. Der parameter timeout wird in Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files-Vorgänge.
prevsharesnapshot Optional in Version 2020-02-10 und höher. Der prevsharesnapshot-Parameter ist ein undurchsichtiger DateTime Wert, der, wenn vorhanden, die vorherige Momentaufnahme angibt.

Wenn sowohl dieser Parameter als auch sharesnapshot vorhanden sind, enthält die Antwort nur Seitenbereiche, die zwischen den beiden Momentaufnahmen geändert wurden. Wenn nur prevsharesnapshot vorhanden ist, enthält die Antwort nur Seitenbereiche, die zwischen dieser Momentaufnahme und der Livefreigabe geändert wurden.

Geänderte Seiten enthalten sowohl aktualisierte als auch gelöschte Seiten.
maxresults Wahlfrei. Version 2026-10-06 und später. Spezifiziert die maximale Anzahl von Bereichen, die auf einer Antwortseite zurückgegeben werden sollen. Wenn maxresults nicht angegeben, versucht der Service, alle verbleibenden Bereiche in einer Antwort zurückzugeben, was bei sehr großen Dateien zu einer Auszeit führen kann.

Wenn maxresults es mehr als 10.000 ist, behandelt der Dienst sie als 10.000. Das Festlegen maxresults auf einen Wert kleiner oder gleich Null führt zu Fehlerantwortcode 400 (ungültige Anforderung).
marker Wahlfrei. Version 2026-10-06 und später. Ein Zeichenkettenwert, der den Teil der Liste identifiziert, der mit der nächsten List Ranges Operation zurückgegeben werden soll. Wenn eine Antwort enthält NextMarker, verwenden Sie diesen Wert wie marker in einem späteren Aufruf, um die Aufzählung fortzusetzen.

Wenn marker ohne maxresultsangegeben ist, beginnt der Service weiterhin mit der Aufzählung von der Markerposition, emittiert aber keinen weiteren NextMarker.

Der Markerwert ist für den Client nicht transparent.

Anforderungsheader

Die erforderlichen und optionalen Anforderungsheader werden in den folgenden Tabellen beschrieben:

Allgemeine Anforderungsheader

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. Gibt die Version des Vorgangs an, der für diese Anforderung verwendet werden soll. Dieser Vorgang wird in Version 2025-05-05 und höher für Dateifreigaben mit aktiviertem NFS-Protokoll unterstützt. Fortsetzungstoken-Parameter (marker und maxresults) sind ab Version 2026-10-06 und später verfügbar.

Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage-Dienste.
Range Wahlfrei. Gibt den Bytebereich an, über den Bereiche (einschließlich) aufgelistet werden sollen. Wenn sie weggelassen wird, werden alle Bereiche für die Datei zurückgegeben.
x-ms-range Wahlfrei. Gibt den Bytebereich an, über den Bereiche (einschließlich) aufgelistet werden sollen.

Wenn sowohl die kopfzeilen Range als auch x-ms-range angegeben werden, verwendet der Dienst den Wert x-ms-range. Weitere Informationen finden Sie unter Angeben des Bereichsheaders für Azure Files-Vorgänge.
x-ms-lease-id:<ID> Wahlfrei. Version 2019-02-02 und höher. Wenn der Header angegeben ist, wird der Vorgang nur ausgeführt, wenn die Lease der Datei aktuell aktiv ist und die in der Anforderung angegebene Lease-ID mit der der Datei übereinstimmt. Andernfalls schlägt der Vorgang mit dem Statuscode 412 fehl (Vorbedingung fehlgeschlagen).

Dieser Header wird ignoriert, wenn sich die Datei in einer Dateifreigabe mit aktiviertem NFS-Protokoll befindet, was Dateileases nicht unterstützt.
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-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.

Dieser Header wird ignoriert, wenn sich das Ziel auf einer Dateifreigabe mit aktiviertem NFS-Protokoll befindet, das den nachfolgenden Punkt standardmäßig unterstützt.

Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.
x-ms-file-support-rename: { <Boolean> } Wahlfrei. Unterstützt in Version 2024-05-04 und höher. Dieser Header ist nur zulässig, wenn prevsharesnapshot Abfrageparameter vorhanden ist. Der boolesche Wert bestimmt, ob die geänderten Bereiche für eine Datei aufgelistet werden sollen, wenn sich der Speicherort der Datei in der vorherigen Momentaufnahme vom Speicherort im Anforderungs-URI unterscheidet, als Ergebnis von Umbenennungs- oder Verschiebungsvorgängen. Wenn der Wert "true" ist, werden die gültigen geänderten Bereiche für die Datei zurückgegeben. Wenn der Wert falsch ist, führt der Vorgang zu einem Fehler mit der Antwort 409 (Konflikt). Der Standardwert ist "false".

Nur SMB-Anforderungsheader

Nichts.

NUR NFS-Anforderungsheader

Nichts.

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 den folgenden Tabellen. Die Antwort kann auch zusätzliche Standard-HTTP-Header enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Allgemeine Antwortheader

Antwortheader Beschreibung
Last-Modified Das Datum/die Uhrzeit der letzten Änderung der Datei. Jeder Vorgang, der die Datei ändert, einschließlich einer Aktualisierung der Metadaten oder Eigenschaften der Datei, ändert die Uhrzeit der letzten Änderung der Datei.
ETag Die ETag enthält einen Wert, der die Version der Datei in Anführungszeichen darstellt.
x-ms-content-length Die Größe der Datei in Byte. Wenn prevsharesnapshot vorhanden ist, beschreibt der Wert die Größe der Datei an der sharesnapshot (wenn der sharesnapshot Abfrageparameter vorhanden ist). Andernfalls wird die Größe der Livedatei beschrieben.
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 oder x-ms-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.

Nur SMB-Antwortheader

Nichts.

NUR NFS-Antwortheader

Nichts.

Antworttext

Der Antworttext enthält eine Liste nicht überlappender gültiger Bereiche, sortiert nach erhöhung des Adressbereichs. Das Format des Antworttexts lautet wie folgt.

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
</Ranges>

Wenn der gesamte Satz von Bereichen der Datei gelöscht wurde, enthält der Antworttext keine Bereiche.

Wenn maxresults in der Anfrage angegeben ist und zusätzliche Bereiche verbleiben, enthält der Antwortkörper ein Element NextMarker . Das Format dieser Antwort lautet wie folgt:

<?xml version="1.0" encoding="utf-8"?>
<Ranges>
  <Range>
    <Start>Start Byte</Start>
    <End>End Byte</End>
  </Range>
  <Range>
    <Start>Start Byte</Start>
    <End>End Byte</End>
  </Range>
  <NextMarker>opaque-string</NextMarker>
</Ranges>

Das Element NextMarker wird weggelassen, wenn keine weiteren Bereiche mehr übrig sind oder wenn maxresults in der Anfrage nicht angegeben ist. Um die Aufzählung fortzusetzen, geben Sie den NextMarker Wert als Parameter marker in der nächsten List Ranges Anfrage an.

Wenn prevsharesnapshot angegeben ist, enthält die Antwort nur die Seiten, die sich zwischen der Zielmomentaufnahme (oder der Livedatei) und der vorherigen Momentaufnahme unterscheiden. Die zurückgegebenen Bereiche umfassen beide Bereiche, die aktualisiert wurden oder gelöscht wurden. Das Format dieser Antwort lautet wie folgt:

<?xml version="1.0" encoding="utf-8"?> 
<Ranges> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
  <ClearRange> 
    <Start>Start Byte</Start>
    <End>End Byte</Start> 
  </ClearRange> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
</Ranges>

Wenn der gesamte Satz von Seiten der Datei gelöscht wurde und der parameter prevsharesnapshot nicht angegeben ist, enthält der Antworttext keine Bereiche.

Ermächtigung

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Bemerkungen

Die Anfangs- und Endbyte-Offsets für jeden Bereich sind inklusive. Weitere Informationen finden Sie in den Beispielen Range Update Operations und Range Clear Operations für Put Range. In diesen Beispielen wird gezeigt, welche Bereiche zurückgegeben werden, wenn Sie einen 512-nicht ausgerichteten Bytebereich aus der Datei schreiben oder löschen.

In einer stark fragmentierten Datei mit einer großen Anzahl von Schreibvorgängen kann eine List Ranges Anforderung aufgrund eines internen Servertimeouts fehlschlagen. Anwendungen, die Bereiche einer Datei mit einer großen Anzahl von Schreibvorgängen abrufen, sollten jeweils eine Teilmenge von Bereichen abrufen.

Ab Version 2020-02-10 können Sie List Ranges mit einem prevsharesnapshot-Parameter aufrufen. Dadurch werden die Bereiche zurückgegeben, die sich zwischen der Livedatei und einer Momentaufnahme oder zwischen zwei Momentaufnahmen der Datei auf Momentaufnahmen unterscheiden. Mithilfe dieser Bereichsunterschiede können Sie eine inkrementelle Momentaufnahme einer Datei abrufen. Inkrementelle Momentaufnahmen sind eine kostengünstige Möglichkeit zum Sichern von Dateien, wenn Sie Ihre eigene Sicherungslösung implementieren möchten.

Ab Version 2026-10-06 können Sie mit einem Parameter maxresults aufrufenList Ranges, um die Anzahl der in einer einzigen Antwort zurückgegebenen Bereiche zu begrenzen. Wenn die Antwort nicht alle verbleibenden Bereiche umfasst, wird ein Element NextMarker im Antwortkörper aufgenommen. Sie können diesen Wert dann als Parameter marker für einen nachfolgenden List Ranges Aufruf verwenden, um die Aufzählung dort fortzusetzen, wo die vorherige Antwort aufgehört hat.

Bei der Verwendung von Fortsetzungstoken beachten Sie Folgendes:

  • Wenn marker ohne maxresultsangegeben ist, reicht der Service von der Markerposition bis zum Ende der Datei zurück, ohne eine weitere NextMarkerzu senden.
  • Wenn die ursprüngliche Anfrage einen Range oder Header x-ms-range enthielt, sollten nachfolgende Fortsetzungsanfragen denselben Bereichsheader enthalten. Der Wert marker ist nur im Kontext des ursprünglichen Bereichs bedeutsam.
  • Wenn marker eine Position über das Ende der Datei hinaus referenziert wird, gibt der Service 400 (Bad Request) zurück.

Bestimmte Vorgänge in einer Datei führen dazu, dass List Ranges fehlschlagen, wenn sie aufgerufen wird, eine inkrementelle Momentaufnahme abzurufen. Der Dienst gibt Folgendes zurück:

  • 404 (Nicht gefunden), wenn Sie eine Datei aufrufen, die in einer der Momentaufnahmen (oder live) nicht vorhanden ist, wenn sharesnapshot nicht angegeben ist).
  • 409 (Konflikt), wenn Sie eine Datei aufrufen, die das Ziel eines Überschreibens Copy nach der Momentaufnahme, angegeben durch prevsharesnapshot.
  • 409 (Konflikt), wenn Sie eine Datei aufrufen, die gelöscht und mit demselben Namen und Speicherort neu erstellt wurde, nachdem die durch prevsharesnapshot angegebene Momentaufnahme erstellt wurde.

Siehe auch

Vorgänge für Dateien

  • Last updated on