Create File
The Create File operation creates a new file or replaces a file. When you call Create File, you only initialize the file. To add content to a file, you call the Put Range operation.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS |  |
Request
You can construct a Create File request by doing the following. We recommend that you use HTTPS.
| Method | Request URI | HTTP version |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Replace the path components that are shown in the request URI with your own, as described in the following table:
| Path component | Description |
|---|---|
myaccount |
The name of your storage account. |
myshare |
The name of your file share. |
mydirectorypath |
Optional. The path to the directory where the file is to be created. If the directory path is omitted, the file will be created within the specified share. If the directory is specified, it must already exist within the share before you can create the file. |
myfile |
The name of the file to create. |
For information about path-naming restrictions, see Name and reference shares, directories, files, and metadata.
URI parameters
You can specify the following additional parameters on the request URI:
| Parameter | Description |
|---|---|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set timeouts for file service operations. |
Request headers
The required and optional request headers are described in the following table:
| Request header | Description |
|---|---|
Authorization |
Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage. |
Date or x-ms-date |
Required. Specifies the Coordinated Universal Time (UTC) time for the request. For more information, see Authorize requests to Azure Storage. |
x-ms-version |
Required for all authorized requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services. |
Content-Length |
Optional. Must be zero if present. |
x-ms-content-length: byte value |
Required. This header specifies the maximum size for the file, up to 4 tebibytes (TiB). |
Content-Type or x-ms-content-type |
Optional. The MIME content type of the file. The default type is application/octet-stream. |
Content-Encoding or x-ms-content-encoding |
Optional. Specifies which content encodings have been applied to the file. This value is returned to the client when the Get File operation is performed on the file resource, and you can use it to decode file content. |
Content-Language or x-ms-content-language |
Optional. Specifies the natural languages that are used by this resource. |
Cache-Control or x-ms-cache-control |
Optional. Azure Files stores this value but doesn't use or modify it. |
x-ms-content-md5 |
Optional. Sets the file's MD5 hash. |
x-ms-content-disposition |
Optional. Sets the file's Content-Disposition header. |
x-ms-type: file |
Required. Set this header to file. |
x-ms-meta-name:value |
Optional. Name-value pairs that are associated with the file as metadata. Metadata names must adhere to the naming rules for C# identifiers. Note: File metadata that's specified via Azure Files isn't accessible from a Server Message Block (SMB) client. |
x-ms-file-permission: { inherit ¦ <SDDL> ¦ <binary> } |
In version 2019-02-02 through 2021-04-10, this header is required if x-ms-file-permission-key isn't specified. As of version 2021-06-08, both headers are optional. This permission is the security descriptor for the file that's specified in the Security Descriptor Definition Language (SDDL) or (version 2024-11-04 or later) in base64-encoded binary security descriptor format. You can specify which format to use with the x-ms-file-permission-format header. You can use this header if the permissions size is 8 kibibytes (KiB) or less. Otherwise, you can use x-ms-file-permission-key. If you specify the header, it must have an owner, group, and discretionary access control list (DACL). You can pass a value of inherit to inherit from the parent directory. |
x-ms-file-permission-format: { sddl ¦ binary } |
Optional. Version 2024-11-04 or later. Specifies whether the value passed in x-ms-file-permission is in SDDL or in binary format. If x-ms-file-permission-key is set to inherit, this header should not be set. If x-ms-file-permission-key is set to any other value than inherit, and if this header is not set, the default value of sddl is used. |
x-ms-file-permission-key: <PermissionKey> |
In version 2019-02-02 through 2021-04-10, this header is required if x-ms-file-permission isn't specified. As of version 2021-06-08, both headers are optional. If neither header is specified, the default value of inherit is used for the x-ms-file-permission header.You can create the key by calling the Create Permission API. |
x-ms-file-attributes |
Required: version 2019-02-02 through 2021-04-10. Optional: version 2021-06-08 and later. This header contains the file system attributes to be set on the file. For more information, see the list of available attributes. The default value is None. |
x-ms-file-creation-time: { now ¦ <DateTime> } |
Required: version 2019-02-02 through 2021-04-10. Optional: version 2021-06-08 and later. The Coordinated Universal Time (UTC) creation time property for the file. A value of now may be used to indicate the time of the request. The default value is now. |
x-ms-file-last-write-time: { now ¦ <DateTime> } |
Required: version 2019-02-02 through 2021-04-10. Optional: version 2021-06-08 and later. The Coordinated Universal Time (UTC) last write property for the file. You can use a value of now to indicate the time of the request. The default value is now. |
x-ms-lease-id: <ID> |
Required if the file has an active lease. Available for version 2019-02-02 and later. |
x-ms-client-request-id |
Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Files. |
x-ms-file-change-time: { now ¦ <DateTime> } |
Optional. Version 2021-06-08 and later. The Coordinated Universal Time (UTC) change time property for the file, in the ISO 8601 format. You can use a value of now to indicate the time of the request. The default value is now. |
x-ms-file-request-intent |
Required if Authorization header specifies an OAuth token. Acceptable value is backup. This header specifies that the Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action or Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action should be granted if they are included in the RBAC policy assigned to the identity that is authorized using the Authorization header. Available for version 2022-11-02 and later. |
x-ms-allow-trailing-dot: { <Boolean> } |
Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in request url should be trimmed or not. For more information, see Naming and referencing shares, directories, files, and metadata. |
Request body
None.
Sample request
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=
Response
The response includes an HTTP status code and a set of response headers.
Status code
A successful operation returns status code 201 (Created).
For information about status codes, see Status and error codes.
Response headers
The response for this operation includes the headers that are described in the following table. The response can also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
| Response header | Description |
|---|---|
ETag |
The ETag contains a value that represents the version of the file. The value is enclosed in quotation marks. |
Last-Modified |
Returns the date and time when the file was last modified. The date format follows RFC 1123. For more information, see Represent date/time values in headers. Any operation that modifies the directory or its properties updates the last modified time. Operations on files don't affect the last modified time of the directory. |
x-ms-request-id |
Uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshoot API operations |
x-ms-version |
Indicates the Azure Files version that's used to execute the request. |
Date |
A UTC date/time value that's generated by the service, which indicates the time when the response was initiated. |
x-ms-request-server-encrypted: true/false |
Version 2017-04-17 and later. The value of this header is set to true if you've successfully encrypted the contents of the request by using the specified algorithm. If the encryption is unsuccessful, the value is false. |
x-ms-file-permission-key |
The key of the permission of the file. |
x-ms-file-attributes |
The file system attributes on the file. For more information, see the list of available attributes. |
x-ms-file-creation-time |
The UTC date/time value that represents the creation time property for the file. |
x-ms-file-last-write-time |
The UTC date/time value that represents the last write time property for the file. |
x-ms-file-change-time |
The UTC date/time that value that represents the change time property for the file. |
x-ms-file-file-id |
The file ID of the file. |
x-ms-file-parent-id |
The parent file ID of the file. |
x-ms-client-request-id |
Used to troubleshoot requests and their corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header if it's present in the request and the value contains no more than 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it isn't present in the response. |
Response body
None.
Sample response
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
Authorization
Only the account owner may call this operation.
File system attributes
| Attribute | Win32 file attribute | Definition |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | A file that's read-only. Applications can read the file, but they can't write to it or delete it. |
| Hidden | FILE_ATTRIBUTE_HIDDEN | The file is hidden. It isn't included in an ordinary directory listing. |
| System | FILE_ATTRIBUTE_SYSTEM | A file that the operating system uses a part of, or uses exclusively. |
| None | FILE_ATTRIBUTE_NORMAL | A file that doesn't have other attributes set. This attribute is valid only when used alone. |
| Archive | FILE_ATTRIBUTE_ARCHIVE | A file that's an archive file. Applications ordinarily use this attribute to mark files for backup or removal. |
| Temporary | FILE_ATTRIBUTE_TEMPORARY | A file that's being used for temporary storage. |
| Offline | FILE_ATTRIBUTE_OFFLINE | The data of a file isn't available immediately. This file system attribute is presented primarily to provide compatibility with Windows. Azure Files doesn't support it with offline storage options. |
| NotContentIndexed | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED | The file isn't to be indexed by the content indexing service. |
| NoScrubData | FILE_ATTRIBUTE_NO_SCRUB_DATA | The user data stream that's not to be read by the background data integrity scanner. This file system attribute is presented primarily to provide compatibility with Windows. |
Remarks
To create a new file, first initialize it by calling Create File and specifying its maximum size, up to 4 TiB. When you're performing this operation, don't include content in the request body. After you've created the file, call Put Range to add content to the file or to modify it.
You can change the size of the file by calling Set File Properties.
If the share or parent directory doesn't exist, then the operation fails with status code 412 (Precondition Failed).
Note
The file properties cache-control, content-type, content-md5, content-encoding, and content-language are separate from the file system properties that are available to SMB clients. SMB clients are unable to read, write, or modify these property values.
To create the file, if the existing file has an active lease, the client must specify a valid lease ID on the request. If the client either doesn't specify a lease ID or specifies an invalid lease ID, Azure Files returns status code 412 (Precondition Failed). If the client specifies a lease ID but the file doesn't have an active lease, Azure Files returns status code 412 (Precondition Failed) in this instance also. If the client specifies a lease ID on a file that doesn't yet exist, Azure Files returns status code 412 (Precondition Failed) for requests that are made against version 2019-02-02 and later.
If an existing file with an active lease is overwritten by a Create File operation, the lease persists on the updated file until it's released.
Create File isn't supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot fails with status code 400 (InvalidQueryParameterValue).