Datei erstellen
Der vorgang Create File erstellt eine neue Datei oder ersetzt eine Datei. Wenn Sie Create Fileaufrufen, initialisieren Sie die Datei nur. Um einer Datei Inhalte hinzuzufügen, rufen Sie den vorgang Put Range auf.
Protokollverfügbarkeit
| Aktiviertes Dateifreigabeprotokoll | Verfügbar |
|---|---|
| SMB |
|
| NFS |
|
Bitten
Sie können eine Create File Anforderung erstellen, indem Sie die folgenden Schritte ausführen. Es wird empfohlen, HTTPS zu verwenden.
| Methode | Anforderungs-URI | HTTP-Version |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Ersetzen Sie die Pfadkomponenten, die im Anforderungs-URI angezeigt werden, durch Ihre eigene, wie in der folgenden Tabelle beschrieben:
| Pfadkomponente | Beschreibung |
|---|---|
myaccount |
Der Name Ihres Speicherkontos. |
myshare |
Der Name Ihrer Dateifreigabe. |
mydirectorypath |
Wahlfrei. Der Pfad zum Verzeichnis, in dem die Datei erstellt werden soll. Wenn der Verzeichnispfad nicht angegeben wird, wird die Datei innerhalb der angegebenen Freigabe erstellt. Wenn das Verzeichnis angegeben ist, muss es bereits innerhalb der Freigabe vorhanden sein, bevor Sie die Datei erstellen können. |
myfile |
Der Name der zu erstellenden Datei. |
Informationen zu Pfadbenennungseinschränkungen finden Sie unter Namen- und Referenzfreigaben, Verzeichnisse, Dateien und Metadaten.
URI-Parameter
Sie können die folgenden zusätzlichen Parameter für den Anforderungs-URI angeben:
| 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 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 UTC-Zeit (Coordinated Universal Time) 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. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage-Dienste. |
Content-Length |
Wahlfrei. Muss null sein, wenn vorhanden. |
x-ms-content-length: byte value |
Erforderlich. Dieser Header gibt die maximale Größe für die Datei an, bis zu 4 Tebibyte (TiB). |
Content-Type oder x-ms-content-type |
Wahlfrei. Der MIME-Inhaltstyp der Datei. Der Standardtyp ist application/octet-stream. |
Content-Encoding oder x-ms-content-encoding |
Wahlfrei. Gibt an, welche Inhaltscodierungen auf die Datei angewendet wurden. Dieser Wert wird an den Client zurückgegeben, wenn der Vorgang "Datei abrufen" für die Dateiressource ausgeführt wird, und Sie können ihn verwenden, um Dateiinhalte zu decodieren. |
Content-Language oder x-ms-content-language |
Wahlfrei. Gibt die natürlichen Sprachen an, die von dieser Ressource verwendet werden. |
Cache-Control oder x-ms-cache-control |
Wahlfrei. Azure Files speichert diesen Wert, verwendet oder ändert ihn jedoch nicht. |
x-ms-content-md5 |
Wahlfrei. Legt den MD5-Hash der Datei fest. |
x-ms-content-disposition |
Wahlfrei. Legt den Content-Disposition Header der Datei fest. |
x-ms-type: file |
Erforderlich. Legen Sie diese Kopfzeile auf filefest. |
x-ms-meta-name:value |
Wahlfrei. Name-Wert-Paare, die der Datei als Metadaten zugeordnet sind. Metadatennamen müssen den Benennungsregeln für C#-Bezeichnerentsprechen. Hinweis: Auf Dateimetadaten, die über Azure Files angegeben sind, kann nicht über einen SMB-Client (Server Message Block) zugegriffen werden. |
x-ms-file-permission: { inherit ¦ <SDDL> ¦ <binary> } |
In Version 2019-02-02 bis 2021-04-10 ist diese Kopfzeile erforderlich, wenn x-ms-file-permission-key nicht angegeben ist. Ab Version 2021-06-08 sind beide Header optional. Diese Berechtigung ist der Sicherheitsdeskriptor für die Datei, die im Security Descriptor Definition Language (SDDL) oder (Version 2024-11-04 oder höher) im base64-codierten binären Sicherheitsdeskriptorformatangegeben ist. Sie können angeben, welches Format mit der x-ms-file-permission-format Kopfzeile verwendet werden soll. Sie können diesen Header verwenden, wenn die Berechtigungsgröße 8 Kibibyte (KiB) oder weniger beträgt. Andernfalls können Sie x-ms-file-permission-keyverwenden. Wenn Sie den Header angeben, muss er über einen Besitzer, eine Gruppe und diskretionäre Zugriffssteuerungsliste (DACL)verfügen. Sie können einen Wert von inherit übergeben, um vom übergeordneten Verzeichnis zu erben. |
x-ms-file-permission-format: { sddl ¦ binary } |
Wahlfrei. Version 2024-11-04 oder höher. Gibt an, ob sich der in x-ms-file-permission übergebene Wert in SDDL oder im Binärformat befindet. Wenn x-ms-file-permission-key auf inheritfestgelegt ist, sollte diese Kopfzeile nicht festgelegt werden. Wenn x-ms-file-permission-key auf einen anderen Wert als inheritfestgelegt ist und wenn dieser Header nicht festgelegt ist, wird der Standardwert sddl verwendet. |
x-ms-file-permission-key: <PermissionKey> |
In Version 2019-02-02 bis 2021-04-10 ist diese Kopfzeile erforderlich, wenn x-ms-file-permission nicht angegeben ist. Ab Version 2021-06-08 sind beide Header optional. Wenn keines der Kopfzeilen angegeben ist, wird der Standardwert von inherit für die x-ms-file-permission Kopfzeile verwendet.Sie können den Schlüssel erstellen, indem Sie die Create Permission-API aufrufen. |
x-ms-file-attributes |
Erforderlich: Version 2019-02-02 bis 2021-04-10. Optional: Version 2021-06-08 und höher. Dieser Header enthält die Dateisystemattribute, die für die Datei festgelegt werden sollen. Weitere Informationen finden Sie in der Liste der verfügbaren Attribute. Der Standardwert ist None. |
x-ms-file-creation-time: { now ¦ <DateTime> } |
Erforderlich: Version 2019-02-02 bis 2021-04-10. Optional: Version 2021-06-08 und höher. Die Utc-Erstellungszeiteigenschaft (Coordinated Universal Time) für die Datei. Ein Wert von now kann verwendet werden, um den Zeitpunkt der Anforderung anzugeben. Der Standardwert ist now. |
x-ms-file-last-write-time: { now ¦ <DateTime> } |
Erforderlich: Version 2019-02-02 bis 2021-04-10. Optional: Version 2021-06-08 und höher. Die utc-Eigenschaft (Coordinated Universal Time) für die Datei zuletzt schreiben. Sie können einen Wert von now verwenden, um den Zeitpunkt der Anforderung anzugeben. Der Standardwert ist now. |
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 |
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-change-time: { now ¦ <DateTime> } |
Wahlfrei. Version 2021-06-08 und höher. Die Utc-Eigenschaft (Coordinated Universal Time) ändert die Zeiteigenschaft für die Datei im ISO 8601-Format. Sie können einen Wert von now verwenden, um den Zeitpunkt der Anforderung anzugeben. Der Standardwert ist now. |
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. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten. |
Anforderungstext
Nichts.
Beispielanforderung
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile HTTP/1.1
Request Headers:
x-ms-version: 2020-02-10
x-ms-date: Mon, 27 Jan 2014 22:41:55 GMT
Content-Type: text/plain; charset=UTF-8
x-ms-content-length: 1024
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=
Antwort
Die Antwort enthält einen HTTP-Statuscode und eine Reihe von Antwortheadern.
Statuscode
Ein erfolgreicher Vorgang gibt den Statuscode 201 (Erstellt) zurück.
Informationen zu Statuscodes finden Sie unter Status- und Fehlercodes.
Antwortheader
Die Antwort für diesen Vorgang enthält die Überschriften, die in der folgenden Tabelle beschrieben werden. Die Antwort kann auch zusätzliche Standard-HTTP-Header 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 der Datei zurück. Das Datumsformat folgt RFC 1123. Weitere Informationen finden Sie unter Darstellen von Datums-/Uhrzeitwerten in Kopfzeilen. Jeder Vorgang, der das Verzeichnis oder seine Eigenschaften ändert, aktualisiert den Zeitpunkt der letzten Änderung. Vorgänge für Dateien wirken sich nicht auf die Uhrzeit der letzten Änderung des Verzeichnisses aus. |
x-ms-request-id |
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 Azure Files-Version an, die zum Ausführen der Anforderung verwendet wird. |
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 Sie den Inhalt der Anforderung mithilfe des angegebenen Algorithmus erfolgreich verschlüsselt haben. Wenn die Verschlüsselung nicht erfolgreich ist, wird der Wert false. |
x-ms-file-permission-key |
Der Schlüssel der Berechtigung der Datei. |
x-ms-file-attributes |
Die Dateisystemattribute in der Datei. Weitere Informationen finden Sie in der Liste der verfügbaren Attribute. |
x-ms-file-creation-time |
Der UTC-Datums-/Uhrzeitwert, der die Erstellungszeiteigenschaft für die Datei darstellt. |
x-ms-file-last-write-time |
Der UTC-Datums-/Uhrzeitwert, der die letzte Schreibzeiteigenschaft für die Datei darstellt. |
x-ms-file-change-time |
Der UTC-Datums-/Uhrzeitwert, der die Änderungszeiteigenschaft für die Datei darstellt. |
x-ms-file-file-id |
Die Datei-ID der Datei. |
x-ms-file-parent-id |
Die übergeordnete Datei-ID der Datei. |
x-ms-client-request-id |
Wird verwendet, um Anforderungen und deren 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 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. |
Antworttext
Nichts.
Beispielantwort
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Date: Mon, 27 Jan 2014 23:00:12 GMT
ETag: "0x8CB14C3E29B7E82"
Last-Modified: Mon, 27 Jan 2014 23:00:06 GMT
x-ms-version: 2014-02-14
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Ermächtigung
Nur der Kontobesitzer kann diesen Vorgang aufrufen.
Dateisystemattribute
| Attribut | Win32-Dateiattribute | Definition |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | Eine Datei, die schreibgeschützt ist. Anwendungen können die Datei lesen, aber sie können nicht darauf schreiben oder löschen. |
| Versteckt | FILE_ATTRIBUTE_HIDDEN | Die Datei ist ausgeblendet. Sie ist nicht in einer normalen Verzeichnisauflistung enthalten. |
| System | FILE_ATTRIBUTE_SYSTEM | Eine Datei, von der das Betriebssystem ausschließlich einen Teil oder ausschließlich verwendet. |
| Nichts | FILE_ATTRIBUTE_NORMAL | Eine Datei, die keine anderen Attribute festgelegt hat. Dieses Attribut ist nur gültig, wenn es allein verwendet wird. |
| Archiv | FILE_ATTRIBUTE_ARCHIVE | Eine Datei, die eine Archivdatei ist. Anwendungen verwenden dieses Attribut normalerweise, um Dateien für die Sicherung oder Entfernung zu markieren. |
| Vorläufig | FILE_ATTRIBUTE_TEMPORARY | Eine Datei, die für temporären Speicher verwendet wird. |
| Offline | FILE_ATTRIBUTE_OFFLINE | Die Daten einer Datei sind nicht sofort verfügbar. Dieses Dateisystem-Attribut wird in erster Linie zur Bereitstellung der Kompatibilität mit Windows dargestellt. Azure Files unterstützt sie nicht mit Offlinespeicheroptionen. |
| NotContentIndexed | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED | Die Datei muss nicht vom Inhaltsindizierungsdienst indiziert werden. |
| NoScrubData | FILE_ATTRIBUTE_NO_SCRUB_DATA | Der Benutzerdatenstrom, der nicht, vom Scanner für die Hintergrunddatenintegrität gelesen zu werden. Dieses Dateisystem-Attribut wird in erster Linie zur Bereitstellung der Kompatibilität mit Windows dargestellt. |
Bemerkungen
Um eine neue Datei zu erstellen, initialisieren Sie sie zuerst, indem Sie Create File aufrufen und ihre maximale Größe angeben, bis zu 4 TiB. Wenn Sie diesen Vorgang ausführen, schließen Sie keinen Inhalt in den Anforderungstext ein. Nachdem Sie die Datei erstellt haben, rufen Sie Put Range auf, um der Datei Inhalte hinzuzufügen oder sie zu ändern.
Sie können die Größe der Datei ändern, indem Sie Set File Propertiesaufrufen.
Wenn das Freigabe- oder übergeordnete Verzeichnis nicht vorhanden ist, schlägt der Vorgang mit dem Statuscode 412 fehl (Vorbedingung fehlgeschlagen).
Anmerkung
Die Dateieigenschaften cache-control, content-type, content-md5, content-encodingund content-language sind von den Dateisystemeigenschaften getrennt, die für SMB-Clients verfügbar sind. SMB-Clients können diese Eigenschaftswerte nicht lesen, schreiben oder ändern.
Wenn die vorhandene Datei über eine aktive Lease verfügt, muss der Client eine gültige Lease-ID für die Anforderung angeben. Wenn der Client entweder keine Lease-ID angibt oder eine ungültige Lease-ID angibt, gibt Azure Files den Statuscode 412 zurück (Vorbedingung fehlgeschlagen). Wenn der Client eine Lease-ID angibt, die Datei jedoch nicht über eine aktive Lease verfügt, gibt Azure Files den Statuscode 412 (Vorbedingung fehlgeschlagen) in dieser Instanz zurück. Wenn der Client eine Lease-ID für eine Datei angibt, die noch nicht vorhanden ist, gibt Azure Files den Statuscode 412 (Vorbedingung fehlgeschlagen) für Anforderungen zurück, die für Version 2019-02-02 und höher vorgenommen werden.
Wenn eine vorhandene Datei mit einer aktiven Lease von einem Create File-Vorgang überschrieben wird, wird die Lease bis zur Veröffentlichung in der aktualisierten Datei beibehalten.
Create File 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 dem Statuscode 400 (InvalidQueryParameterValue) fehl.