Bereich platzieren
Der vorgang Put Range schreibt einen Bytebereich in eine Datei. Dieser Vorgang wird in Version 2025-05-05 und höher für Dateifreigaben mit aktiviertem NFS-Protokoll unterstützt.
Protokollverfügbarkeit
| Aktiviertes Dateifreigabeprotokoll | Verfügbar |
|---|---|
| SMB |
|
| NFS |
|
Bitten
Die Put Range Anforderung wird wie folgt erstellt. Es wird empfohlen, HTTPS zu verwenden.
| Methode | Anforderungs-URI | HTTP-Version |
|---|---|---|
| STELLEN | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
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. |
Informationen zu Pfadbenennungseinschränkungen finden Sie unter Namen- und Referenzfreigaben, Verzeichnisse, Dateien und Metadaten.
URI-Parameter
Die folgenden zusätzlichen Parameter können für den Anforderungs-URI angegeben werden.
| Parameter | Beschreibung |
|---|---|
timeout |
Wahlfrei. Der parameter timeout wird in Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Dateidienstvorgänge. |
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. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage-Dienste. |
Range oder x-ms-range |
Es ist entweder Range oder x-ms-range erforderlich.Gibt den zu schreibenden Bytebereich an. Sowohl der Anfang als auch das Ende des Bereichs müssen angegeben werden. Dieser Header wird durch die HTTP/1.1-Protokollspezifikationdefiniert. Bei einem Aktualisierungsvorgang kann der Bereich bis zu 4 MiB groß sein. Bei einem eindeutigen Vorgang kann der Bereich bis zum Wert der vollständigen Größe der Datei liegen. Der Dateidienst akzeptiert nur einen einzelnen Bytebereich für die kopfzeilen Range und x-ms-range, und der Bytebereich muss im folgenden Format angegeben werden: bytes=startByte-endByte.Wenn sowohl 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 Dateidienstvorgänge. |
Content-Length |
Erforderlich. Gibt die Anzahl der Im Anforderungstext übertragenen Bytes an. Wenn der x-ms-write Header auf clearfestgelegt ist, muss der Wert dieser Kopfzeile auf 0festgelegt werden. |
Content-MD5 |
Wahlfrei. Ein MD5-Hash des Inhalts. Dieser Hash wird verwendet, um die Integrität der Daten während des Transports zu überprüfen. Wenn der Content-MD5 Header angegeben ist, vergleicht Azure Files den Hash des Inhalts, der mit dem gesendeten Headerwert eingegangen ist. Wenn die beiden Hashes nicht übereinstimmen, schlägt der Vorgang mit dem Fehlercode 400 (Ungültige Anforderung) fehl.Die Content-MD5 Kopfzeile ist nicht zulässig, wenn die x-ms-write Kopfzeile auf clearfestgelegt ist. Wenn sie in der Anforderung enthalten ist, gibt der Dateidienst den Statuscode 400 (ungültige Anforderung) zurück. |
x-ms-write: { update ¦ clear } |
Erforderlich. Sie müssen eine der folgenden Optionen angeben:
|
x-ms-lease-id:<ID> |
Erforderlich, wenn die Datei über eine aktive Lease verfügt. Verfügbar für Version 2019-02-02 und höher. 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-last-write-time: { now ¦ preserve } |
Wahlfrei. Version 2021-06-08 und höher. Sie können eine der folgenden Optionen angeben:
|
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. |
Nur SMB-Anforderungsheader
Nichts.
NUR NFS-Anforderungsheader
Nichts.
Anforderungstext
Die Daten, die den Bereich darstellen, der hochgeladen werden soll.
Beispielanforderung: Bytebereich aktualisieren
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Beispielanforderung: Bytebereich löschen
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Antwort
Die Antwort enthält einen HTTP-Statuscode und eine Reihe von Antwortheadern.
Statuscode
Ein erfolgreicher Vorgang gibt den Statuscode 201 (Erstellt) zurück. Weitere 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 |
|---|---|
ETag |
Das ETag enthält einen Wert, der die Version der Datei darstellt. Der Wert wird in Anführungszeichen eingeschlossen. |
Last-Modified |
Gibt das Datum und die Uhrzeit der letzten Änderung des Verzeichnisses zurück. Das Datumsformat folgt RFC 1123. Weitere Informationen finden Sie unter Darstellen von Datums-/Uhrzeitwerten in Kopfzeilen. Jeder Vorgang, der die Freigabe oder die zugehörigen Eigenschaften oder Metadaten ändert, aktualisiert den Zeitpunkt der letzten Änderung. Vorgänge für Dateien wirken sich nicht auf den Zeitpunkt der letzten Änderung der Freigabe aus. |
Content-MD5 |
Dieser Header wird zurückgegeben, damit der Client auf die Nachrichteninhaltsintegrität überprüfen kann. Der Wert dieses Headers wird vom Dateidienst berechnet. Er ist nicht notwendigerweise identisch mit dem Wert, der in den Anforderungsheadern angegeben ist. |
x-ms-request-id |
Identifiziert die anforderung eindeutig, die durchgeführt wurde, und kann verwendet werden, um die Anforderung zu behandeln. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge. |
x-ms-version |
Gibt die Dateidienstversion an, die zum Ausführen der Anforderung verwendet wurde. |
Date |
Ein UTC-Datums-/Uhrzeitwert, der vom Dienst generiert wird, der die Uhrzeit angibt, zu der die Antwort initiiert wurde. |
x-ms-request-server-encrypted: { true ¦ false } |
Version 2017-04-17 und höher. Der Wert dieses Headers wird auf true festgelegt, wenn der Inhalt der Anforderung mithilfe des angegebenen Algorithmus erfolgreich verschlüsselt wird. Andernfalls wird der Wert auf falsefestgelegt. |
x-ms-client-request-id |
Dieser Header kann zum Behandeln von Anforderungen und entsprechenden Antworten verwendet werden. Der Wert dieses Headers ist gleich dem Wert des x-ms-client-request-id Headers, wenn er in der Anforderung vorhanden ist und der Wert nicht mehr als 1.024 sichtbare ASCII-Zeichen enthält. Wenn der x-ms-client-request-id-Header in der Anforderung nicht vorhanden ist, ist er in der Antwort nicht vorhanden. |
x-ms-file-last-write-time |
Version 2021-06-08 und höher. Die letzte Schreibzeit für die Datei im ISO 8601-Format. Beispiel: 2017-05-10T17:52:33.9551861Z. |
Nur SMB-Antwortheader
Nichts.
NUR NFS-Antwortheader
Nichts.
Antworttext
Nichts.
Beispielantwort
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Ermächtigung
Nur der Kontobesitzer kann diesen Vorgang aufrufen.
Bemerkungen
Der vorgang Put Range schreibt einen Bytebereich in eine Datei. Dieser Vorgang kann nur für eine vorhandene Datei aufgerufen werden. Es kann nicht aufgerufen werden, um eine neue Datei zu erstellen. Das Aufrufen von Put Range mit einem Dateinamen, der derzeit nicht vorhanden ist, gibt den Statuscode 404 (Nicht gefunden) zurück.
Rufen Sie zum Erstellen einer neuen Datei Create Fileauf. Eine Datei kann bis zu 4 TiB groß sein.
Ein Put Range Vorgang ist 10 Minuten pro MiB zulässig. Wenn der Vorgang im Durchschnitt länger als 10 Minuten pro MiB dauert, ist es zeitüberschreitung.
Wenn die Datei über eine aktive Lease verfügt, muss der Client eine gültige Lease-ID für die Anforderung angeben, um einen Bereich zu schreiben.
Bereichsaktualisierungsvorgänge
Das Aufrufen von Put Range mit der Option Update führt einen direkten Schreibzugriff auf die angegebene Datei aus. Alle Inhalte im angegebenen Bereich werden mit dem Update überschrieben. Jeder Bereich, der mit Put Range für einen Aktualisierungsvorgang übermittelt wird, kann bis zu 4 MiB groß sein. Wenn Sie versuchen, einen Bereich hochzuladen, der größer als 4 MiB ist, gibt der Dienst den Statuscode 413 zurück (Anforderungsentität zu groß).
Vorgänge "Bereich löschen"
Das Aufrufen von Put Range mit der Option Clear gibt den Speicherplatz im Speicher frei, solange der angegebene Bereich 512-Byte ausgerichtet ist. Bereiche, die gelöscht wurden, werden nicht mehr als Teil der Datei nachverfolgt und werden nicht in der antwort Listenbereich zurückgegeben. Wenn der angegebene Bereich nicht 512-Byte ausgerichtet ist, schreibt der Vorgang Nullen an den Anfang oder das Ende des Bereichs, der nicht 512-Byte ausgerichtet ist, und gibt den Rest des Bereichs innerhalb der 512-Byte-Ausrichtung frei.
Alle Bereiche, die nicht gelöscht wurden, werden in der Antwort Listenbereiche zurückgegeben. Ein Beispiel finden Sie im folgenden Abschnitt "Beispiel für nicht ausgerichteten eindeutigen Bereich".
Datei-Lease-
Sie können Lease File aufrufen, um eine exklusive Schreibsperre für die Datei für andere Schreibvorgänge für eine unendliche Dauer abzurufen.
SMB-Clientbytebereich sperrt
Mit dem SMB-Protokoll können Bytebereichssperren Lese- und Schreibzugriff auf Bereiche einer Datei verwalten. Dies bedeutet, dass Put Range für eine Datei, die sich auf einer Dateifreigabe mit aktiviertem SMB-Protokoll befindet, fehlschlägt, wenn ein SMB-Client über eine Sperre verfügt, die sich mit dem durch den Put Range-Vorgang angegebenen Bereich überschneidet, indem x-ms-rangeverwendet wird. Weitere Informationen finden Sie unter Verwalten von Dateisperren.
NFS-Clientbytebereichssperren
Die POSIX-Bytebereichssperren des NFS-Protokolls sind in der Natur beratend, daher schlägt die Put Range für eine Datei auf einer Dateifreigabe mit aktiviertem NFS-Protokoll nicht fehl, auch wenn es eine widersprüchliche Bytebereichssperre gibt, die von einem NFS-Client gehalten wird.
SMB-Clientverzeichnisänderungsbenachrichtigungen
Das SMB-Protokoll unterstützt die FindFirstChangeNotification API-Funktion, mit der Anwendungen erkennen können, wann Änderungen im Dateisystem auftreten. Sie kann erkennen, wann eine Datei oder ein Verzeichnis hinzugefügt, geändert oder gelöscht wird und wenn sich die Größe, Attribute oder Sicherheitsbeschreibungen einer Datei ändern. SMB-Clients, die diese API verwenden, erhalten keine Benachrichtigungen, wenn eine Datei- oder Verzeichnisänderung über die Rest-API von Azure Files erfolgt. Durch andere SMB-Clients verursachte Änderungen verteilen jedoch Benachrichtigungen.
Beispiel für nicht ausgerichteten eindeutigen Bereich
Angenommen, eine Datei wird mit Create File erstellt, und ein einzelner Bereich wird mit Put Rangegeschrieben, wie folgt:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Wenn Sie einen Listenbereiche ausführen, Vorgang für die Datei ausgeführt wird, wird der folgende Antworttext zurückgegeben:
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Nehmen wir nun an, dass ein Vorgang für einen nicht ausgerichteten Bereichsbytebereich ausgeführt wird:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Ein nachfolgendes Listenbereiche Vorgangs in der Datei gibt den folgenden Antworttext zurück:
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
Beachten Sie, dass Nullen aus 768-1024 und 2048-2304 in den nicht ausgerichteten Raum geschrieben wurden.
Put Range wird für eine Freigabemomentaufnahme nicht unterstützt, bei der es sich um eine schreibgeschützte Kopie einer Freigabe handelt. Ein Versuch, diesen Vorgang für eine Freigabemomentaufnahme auszuführen, schlägt mit 400 (InvalidQueryParameterValue) fehl.