Put Range
Mit dem Put Range-Vorgang wird ein Bytebereich in eine Datei geschrieben.
Protokollverfügbarkeit
| Aktiviertes Dateifreigabeprotokoll | Verfügbar |
|---|---|
| SMB |
|
| NFS |
|
Anforderung
Die Put Range-Anforderung kann wie folgt erstellt werden. Es wird empfohlen, HTTPS zu verwenden.
| Methode | Anforderungs-URI | HTTP-Version |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
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. |
Informationen zu Einschränkungen bei der Pfadbenennung finden Sie unter Namens- und Verweisfreigaben, Verzeichnisse, Dateien und Metadaten.
URI-Parameter
Im Anforderungs-URI können die folgenden zusätzlichen Parameter angegeben werden.
| Parameter | Beschreibung |
|---|---|
timeout |
Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Dateidienstvorgänge. |
Anforderungsheader
Die erforderlichen und optionalen Anforderungsheader werden in der folgenden Tabelle 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 oder x-ms-range |
Entweder Range oder x-ms-range ist erforderlich.Gibt den Bereich der zu schreibenden Bytes an. Sowohl der Anfang als auch das Ende des Bereichs müssen angegeben werden. Dieser Header wird durch die HTTP/1.1-Protokollspezifikation definiert. Bei einem Updatevorgang kann der Bereich bis zu 4 MiB groß sein. Bei einem Löschvorgang kann der Bereich dem Wert der Gesamtgröße der Datei entsprechen. Der Dateidienst akzeptiert nur einen einzelnen Bytebereich für die Range Header und x-ms-range , und der Bytebereich muss im folgenden Format angegeben werden: bytes=startByte-endByte.Wenn 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 Dateidienstvorgänge. |
Content-Length |
Erforderlich. Gibt die Anzahl der Bytes an, die im Anforderungstext übertragen werden. Wenn der x-ms-write Header auf clearfestgelegt ist, muss der Wert dieses Headers auf 0festgelegt werden. |
Content-MD5 |
Optional. Ein MD5-Hash des Inhalts. Mithilfe des Hash wird die Integrität der Daten während der Übertragung überprüft. Wenn der Content-MD5 Header angegeben ist, vergleicht Azure Files den Hash des eingetroffenen Inhalts mit dem gesendeten Headerwert. Wenn die beiden Hashs nicht übereinstimmen, schlägt der Vorgang mit Fehlercode 400 (Ungültige Anforderung) fehl.Der Content-MD5 Header ist nicht zulässig, wenn der x-ms-write Header auf clearfestgelegt ist. Wenn es in der Anforderung enthalten ist, gibt der Dateidienst status Code 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. |
x-ms-client-request-id |
Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (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 Azure Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Optional. Version 2021-06-08 und höher. Sie können eine der folgenden Optionen angeben:
|
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 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
Die Daten, die den hochzuladenden Bereich darstellen.
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 den HTTP-Statuscode und einen Satz von Antwortheadern.
Statuscode
Bei einem erfolgreichen Vorgang wird der Statuscode 201 (Erstellt) zurückgegeben.
Weitere Informationen zu status Codes finden Sie unter Status- und Fehlercodes.
Antwortheader
Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann außerdem weitere HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.
| 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 entspricht RFC 1123. Weitere Informationen finden Sie unter Darstellen von Datums-/Uhrzeitwerten in Headern. Bei jedem Vorgang, durch den die Freigabe, deren Eigenschaften oder Metadaten geändert werden, wird der Zeitpunkt der letzten Änderung aktualisiert. 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 die Integrität des Nachrichteninhalts überprüfen kann. Der Wert dieses Headers wird vom Dateidienst berechnet. Er ist nicht unbedingt identisch mit dem Wert, der in den Anforderungsheadern angegeben wird. |
x-ms-request-id |
Identifiziert die durchgeführte Anforderung eindeutig und kann zur Problembehandlung für die Anforderung verwendet werden. 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 den Zeitpunkt angibt, zu dem 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 wurde. Andernfalls wird der Wert auf false festgelegt. |
x-ms-client-request-id |
Dieser Header kann zur Problembehandlung 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. |
Antworttext
Keine
Beispiel für eine Antwort
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
Authorization
Dieser Vorgang kann nur vom Kontobesitzer aufgerufen werden.
Bemerkungen
Mit dem Put Range-Vorgang wird ein Bytebereich in eine Datei geschrieben. Dieser Vorgang kann nur für eine vorhandene Datei aufgerufen werden. Sie kann nicht aufgerufen werden, um eine neue Datei zu erstellen. Wenn Sie Put Range mit einem derzeit nicht vorhandenen Dateinamen aufrufen, wird status Code 404 (Nicht gefunden) zurückgegeben.
Rufen Sie Create File auf, um eine neue Datei zu erstellen. Eine Datei kann bis zu 4 TiB groß sein.
Ein Put Range Vorgang ist 10 Minuten pro MiB zulässig. Wenn der Vorgang durchschnittlich länger als 10 Minuten pro MiB dauert, tritt ein Zeitüberschreitung auf.
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
Wenn Put Range mit der Option Update aufgerufen wird, wird ein direkter Schreibvorgang in die angegebene Datei ausgeführt. Sämtlicher Inhalt im angegebenen Bereich wird durch das Update überschrieben. Jeder Bereich, der mit Put Range für einen Updatevorgang ü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 status Code 413 (Request Entity Too Large) zurück.
Vorgänge zum Löschen des Bereichs
Durch den Aufruf von Put Range mit der Option Clear wird Platz im Speicher freigegeben, solange der angegebene Bereich auf 512-Bytes ausgerichtet ist. Gelöschte Bereiche werden nicht mehr als Teil der Datei nachverfolgt und 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 frei, der 512 Byte ausgerichtet ist.
Alle Bereiche, die nicht gelöscht wurden, werden in der Antwort Auflisten von Bereichen zurückgegeben. Ein Beispiel finden Sie im folgenden Abschnitt "Beispiel für einen nicht ausgerichteten eindeutigen Bereich".
Dateileasing
Sie können Lease File aufrufen, um eine exklusive Schreibsperre für die Datei für andere Schreibvorgänge für eine unbegrenzte Dauer zu erhalten.
SMB-Clientbytebereichssperren
Das SMB-Protokoll ermöglicht Bytebereichssperren zum Verwalten des Lese- und Schreibzugriffs auf Regionen einer Datei. Dies bedeutet, dass Put Range fehlschlägt, wenn ein SMB-Client über eine Sperre verfügt, die sich mit dem durch den Put Range Vorgang x-ms-rangeangegebenen Bereich überschneidet. Weitere Informationen finden Sie unter Verwalten von Dateisperren.
Änderungsbenachrichtigungen für SMB-Clientverzeichnisse
Das SMB-Protokoll unterstützt die FindFirstChangeNotification-API-Funktion , mit der Anwendungen erkennen können, wenn Änderungen im Dateisystem auftreten. Er kann erkennen, wann eine Datei oder ein Verzeichnis hinzugefügt, geändert oder gelöscht wird und wann 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 Azure Files REST-API erfolgt. Änderungen, die von anderen SMB-Clients verursacht werden, werden jedoch Benachrichtigungen weitergegeben.
Beispiel für einen nicht ausgerichteten eindeutigen Bereich
Angenommen, eine Datei wird mit Datei erstellen erstellt, und ein einzelner Bereich wird wie folgt mit Put Rangegeschrieben:
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
Beim Ausführen eines Listenbereichsvorgangs für die Datei 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 nicht ausgerichteter Clear Range-Bytebereichsvorgang 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 nachfolgender Listenbereichsvorgang für die 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 in den nicht ausgerichteten Bereich von 768 bis 1024 und 2048 bis 2304 Nullen (0) geschrieben wurden.
Put Rangewird nicht für eine Freigabe Momentaufnahme unterstützt, bei der es sich um eine schreibgeschützte Kopie einer Freigabe handelt. Ein Versuch, diesen Vorgang für eine Freigabe auszuführen, Momentaufnahme mit 400 (InvalidQueryParameterValue) fehlschlägt.