List Ranges

Artikel
03/29/2023

Der Vorgang List Ranges gibt die Liste der gültigen Bereiche für eine Datei zurück.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll	Verfügbar
SMB
NFS

Anforderung

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

Methode	Anforderungs-URI	HTTP-Version
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	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 ü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`	Optional. Version 2017-04-17 und höher. Der `sharesnapshot` Parameter ist ein undurchsichtiger `DateTime` Wert, der, wenn vorhanden, die Freigabe angibt, Momentaufnahme für die Abfrage der Datei verwendet werden soll.
`timeout`	Optional. Der `timeout`-Parameter wird in Sekunden angegeben. 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, den vorherigen Momentaufnahme angibt. Wenn sowohl dieser Parameter `sharesnapshot` als auch 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 diesem Momentaufnahme und der Livefreigabe geändert wurden. Geänderte Seiten umfassen sowohl aktualisierte als auch gelöschte Seiten.

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. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
`Range`	Optional. Gibt den Bereich von Bytes an, über den Bereiche aufgelistet werden sollen (jeweils einschließlich). Wenn keine Angabe erfolgt, werden alle Bereiche für die Datei zurückgegeben.
`x-ms-range`	Optional. Gibt den Bereich von Bytes an, über den Bereiche aufgelistet werden sollen (jeweils einschließlich). Wenn die Header `Range` und `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>`	Optional. Version 2019-02-02 und höher. Wenn der Header angegeben ist, wird der Vorgang nur ausgeführt, wenn die Lease der Datei derzeit aktiv ist und die in der Anforderung angegebene Lease-ID mit der der Datei übereinstimmt. Andernfalls schlägt der Vorgang mit status Code 412 (Vorbedingung fehlgeschlagen) fehl.
`x-ms-client-request-id`	Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der bei der Konfiguration der Protokollierung in den Protokollen aufgezeichnet wird. 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-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 in der Anforderungs-URL vorhandener nachgestellter Punkt gekürzt werden soll oder nicht. 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
`Last-Modified`	Datum/Uhrzeit der letzten Änderung der Datei. Jeder Vorgang, der die Datei ändert, einschließlich einer Aktualisierung der Metadaten oder Eigenschaften der Datei, ändert den Zeitpunkt der letzten Änderung der Datei.
`ETag`	Enthält `ETag` einen Wert, der die Version der Datei in Anführungszeichen darstellt.
`x-ms-content-length`	Dies ist die Größe der Datei in Byte. Wenn `prevsharesnapshot` vorhanden ist, beschreibt der Wert die Größe der Datei am `sharesnapshot` (wenn der `sharesnapshot` Abfrageparameter vorhanden ist). Andernfalls wird die Größe der Livedatei beschrieben.
`x-ms-request-id`	Dieser Header identifiziert eindeutig die Anforderung, die gestellt wurde, 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 Probleme mit Anforderungen und entsprechenden Antworten zu beheben. Der Wert dieses Headers entspricht dem Wert des `x-ms-client-request-id` Headers, wenn er in der Anforderung vorhanden ist. Der Wert ist 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

Der Antworttext enthält eine Liste mit gültigen, nicht überlappenden Seitenbereichen, die ansteigend nach Adressseitenbereich sortiert sind. Das Format des Antworttexts sieht wie folgt aus.

<?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 Bereichssatz der Datei gelöscht wurde, enthält der Antworttext keine Bereiche.

Wenn prevsharesnapshot angegeben ist, enthält die Antwort nur die Seiten, die sich zwischen dem Ziel Momentaufnahme (oder der Livedatei) und dem vorherigen Momentaufnahme unterscheiden. Die zurückgegebenen Bereiche umfassen beide Bereiche, die aktualisiert 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 Seitensatz der Datei gelöscht wurde und der prevsharesnapshot Parameter nicht angegeben ist, enthält der Antworttext keine Bereiche.

Autorisierung

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Hinweise

Die Start- und Endbyteoffsets für die einzelnen Seitenbereiche sind inklusiv. Weitere Informationen finden Sie in den Beispielen für Vorgänge zum Aktualisieren von Bereichs - und Bereichslöschvorgängen für Put Range. Diese Beispiele zeigen, welche Bereiche zurückgegeben werden, wenn Sie einen 512-Bytebereich ohne Ausrichtung aus der Datei schreiben oder löschen.

In einer stark fragmentierten Datei mit einer hohen Anzahl von Schreibvorgängen kann eine List Ranges-Anforderung zu einem Fehler aufgrund eines internen Servertimeouts führen. Anwendungen, die Bereiche einer Datei mit vielen Schreibvorgängen abrufen, sollten immer jeweils eine Teilmenge der Seitenbereiche abrufen.

Ab Version 2020-02-10 können Sie mit einem prevsharesnapshot Parameter aufrufenList Ranges. Dadurch werden die Bereiche zurückgegeben, die sich zwischen der Livedatei und einem Momentaufnahme oder zwischen zwei Momentaufnahmen der Datei in 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.

Bei bestimmten Vorgängen für eine Datei tritt List Ranges ein Fehler auf, wenn sie aufgerufen wird, um eine inkrementelle Momentaufnahme abzurufen. Der Dienst gibt Folgendes zurück:

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

Weitere Informationen

Vorgänge für Dateien