Bereich von URL festlegen

  • Artikel

Der Put Range From URL Vorgang erstellt einen neuen Bereich, der als Teil einer Datei festgelegt werden soll, in der der Inhalt aus einer URL gelesen wird. Diese API ist ab Version 2019-02-02 verfügbar.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll Verfügbar
SMB Ja
NFS Nein

Anforderung

Die Put Range From URL-Anforderung kann wie folgt erstellt werden. Es wird empfohlen, HTTPS zu verwenden. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos:

Methode Anforderungs-URI HTTP-Version
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1

URI-Parameter

Parameter BESCHREIBUNG
timeout Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files Vorgä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. Für Put Range From URLmuss die Version 2019-02-02 oder höher sein.
x-ms-copy-source:name Erforderlich. Gibt die URL der Quelldatei an. Der Wert kann eine URL mit einer Länge von bis zu 2 KiB sein, die eine Datei angibt. Der Wert sollte so URL-codiert sein, wie er in einem Anforderungs-URI verwendet wird. Die Quelldatei muss entweder öffentlich sein oder über eine Shared Access Signature autorisiert werden. Wenn die Quelldatei öffentlich ist, ist zum Ausführen des Vorgangs keine Autorisierung erforderlich. Hier sind einige Beispiele für Quellobjekt-URLs:
  • https://myaccount.file.core.windows.net/myshare/mydir/myfile
  • https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>
x-ms-copy-source-authorization: <scheme> <signature> Optional. Gibt das Autorisierungsschema und die Signatur für die Kopierquelle an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
Nur der Schematräger wird für Microsoft Entra unterstützt.
Dieser Header wird in Version 2020-10-02 und höher unterstützt.
x-ms-write: { update } Erforderlich. Sie müssen nur updateangeben. Die Anforderung schlägt fehl, wenn sie mit clearaufgerufen wird. Der update Wert schreibt die Vom Anforderungstext angegebenen Bytes in die angegebenen Bereiche.
Range oder x-ms-range Erforderlich. 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.

Azure Files akzeptiert nur einen einzelnen Bytebereich für die Range Header undx-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 Azure Files Vorgänge.
x-ms-source-range Erforderlich. Gibt den Bereich der Bytes an, die aus der Quelle gelesen werden sollen. Sowohl der Anfang als auch das Ende des Bereichs müssen angegeben werden.

Azure Files akzeptiert nur einen einzelnen Bytebereich für die Range Header undx-ms-range, und der Bytebereich muss im folgenden Format angegeben werden: bytes=startByte-endByte.

Der Quellbereich kann bis zu 4 MiB groß sein. Wenn die Quellbereichsgröße 4 MiB überschreitet, gibt Azure Files status Code 413 (Anforderungsentität zu groß) zurück. Wenn die Quellbereichsgröße nicht mit der Größe des Bereichs (Zielbereich) übereinstimmt, gibt der Dienst status Code 400 (Ungültige Anforderung) zurück.
Content-Length Erforderlich. Gibt die Anzahl der Bytes an, die im Anforderungstext übertragen werden. Der Wert dieses Headers muss auf 0 festgelegt sein. Wenn die Länge nicht 0ist, schlägt der Vorgang mit dem status Code 400 (Ungültige Anforderung) fehl.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der beim Konfigurieren 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-source-content-crc64 Optional. Ein CRC64-Hash des angegebenen Bereichs aus dem URI. Dieser Hash wird verwendet, um die Integrität des Bereichs während des Transports der Daten aus dem URI zu überprüfen. Wenn dieser Header angegeben wird, vergleicht Azure Files den Hash des Inhalts, der aus der Copy-Source-Quelle eingegangen ist, mit diesem Headerwert.

Hinweis: Dieser CRC64-Hash wird nicht mit der Datei gespeichert.

Wenn die beiden Hashs nicht übereinstimmen, schlägt der Vorgang mit Fehlercode 400 (Ungültige Anforderung) fehl.
x-ms-source-if-match-crc64 Optional. Ein CRC64-Prüfsummenwert. Geben Sie diesen Header an, um den Vorgang nur auszuführen, wenn die Prüfsumme des angegebenen Bereichs, der aus der Quelle gelesen wird, mit der angegebenen Prüfsumme übereinstimmt.

Wenn die angegebene Bedingung nicht erfüllt ist, gibt Azure Files status Code 412 (Vorbedingung fehlgeschlagen) zurück.
x-ms-source-if-none-match-crc64 Optional. Ein CRC64-Prüfsummenwert. Geben Sie diesen Header an, um den Vorgang nur auszuführen, wenn sich die Prüfsumme des angegebenen Bereichs, der aus der Quelle gelesen wird, von der angegebenen Prüfsumme unterscheidet.

Wenn die angegebene Bedingung nicht erfüllt ist, gibt Azure Files status Code 412 (Vorbedingung fehlgeschlagen) zurück.
x-ms-lease-id:<ID> Erforderlich, wenn die Datei über eine aktive Lease verfügt. Um diesen Vorgang für eine Datei mit einer aktiven Lease auszuführen, geben Sie die gültige Lease-ID für diesen Header an.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der in den Analyseprotokollen aufgezeichnet wird, wenn die Azure Storage Analytics Protokollierung aktiviert ist. Es wird dringend empfohlen, diesen Header zu verwenden, wenn Sie clientseitige Aktivitäten mit Anforderungen korrelieren, die vom Server empfangen werden. Weitere Informationen finden Sie unter Überwachen von Blob Storage.
x-ms-file-last-write-time: { now ¦ preserve } Optional. Version 2021-06-08 und höher. Sie können eine der folgenden Optionen angeben:
  • now: Standardwert. Updates den Zeitstempel des letzten Schreibvorgangs auf den Zeitpunkt der Anforderung.
  • preserve: Der vorhandene Zeitstempel des letzten Schreibvorgangs bleibt unverändert.
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.
x-ms-source-allow-trailing-dot: { <Boolean> } Optional. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein nachgestellter Punkt in der Quell-URL gekürzt werden soll. Dieser Header sollte nur angegeben werden, wenn die Kopierquelle eine Azure-Datei ist. Dieser Header wird für keinen anderen Kopierquelltyp unterstützt. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

Anforderungstext

Kein Anforderungstext.

Beispiel für eine Anforderung

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D 
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT  
x-ms-version: 2019-02-02 
x-ms-range: bytes=100-1023  
x-ms-source-range: bytes=200-1123  
x-ms-source-content-crc64: 3bedb8b3730fc205 
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0

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 Enthält einen Wert, den Sie zum bedingten Ausführen von Vorgängen verwenden können. Der Wert wird in Anführungszeichen eingeschlossen.
Last-Modified Das Datum und die Uhrzeit der letzten Änderung der Datei. Das Datumsformat entspricht RFC 1123. Weitere Informationen finden Sie unter Darstellung von Datums-/Uhrzeitwerten in Headern.

Jeder Schreibvorgang für die Datei, einschließlich Aktualisierungen der Metadaten oder Eigenschaften der Datei, ändert den Zeitpunkt der letzten Änderung der Datei. 
x-ms-request-id Identifiziert die durchgeführte Anforderung eindeutig, und Sie können sie zur Problembehandlung für die Anforderung verwenden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
x-ms-version Gibt die FileREST-API-Version 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-content-crc64 Wird zurückgegeben, damit der Client die Integrität des Nachrichteninhalts überprüfen kann. Der Wert dieses Headers wird von Azure Files berechnet. Er ist nicht unbedingt identisch mit dem Wert, der in den Anforderungsheadern angegeben wird.
x-ms-client-request-id 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 (z. B. 2017-05-10T17:52:33.9551861Z).

Beispiel für eine Antwort

Response Status:  
HTTP/1.1 201 Created  

Response Headers:
Date: Sun, 22 Aug 2020 01:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT  
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205 
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0 

Authorization

Dieser Vorgang kann vom Kontobesitzer und von jeder Person mit einer Shared Access Signature mit Schreibberechtigungen in diese Datei oder die Azure-Dateifreigabe aufgerufen werden.

Hinweise

Der Put Range From URL Vorgang schreibt einen Datenbereich in eine Datei. Wenn die API für eine nicht vorhandene Datei auf dem Ziel aufgerufen wird, gibt die API HTTP-status Code 404 (Nicht gefunden) zurück.

In Version 2020-10-02 und höher wird Microsoft Entra Autorisierung für die Quelle des Kopiervorgangs unterstützt.

Zum Erstellen einer neuen Datei rufen Sie Create File auf.

Put Range From URL operation gibt nur dann success 201 (Created) zurück, wenn der angegebene Bereich in die Datei geschrieben wird.

Dateilesevorgang
Put Range From URL verwendet Get File , um Daten und Metadaten, Attribute und ACLs aus der Quelle zu lesen.

Dateiaktualisierungsvorgang
Das Aufrufen Put Range From URL mit der Option "update" führt einen direkten Schreibvorgang für die angegebene Datei aus. Alle Inhalte in der angegebenen Datei werden mit dem Update überschrieben.  

Die Bereichsgröße im Put Range From URL Vorgang für einen Updatevorgang kann bis zu 4 MiB groß sein. Wenn Sie versuchen, einen Bereich hochzuladen, der größer als 4 MiB ist, gibt Azure Files status Code 413 (RequestEntityTooLarge) zurück.