创建文件（FileREST API） - Azure 文件

协议可用性

已启用文件共享协议


   mydirectorypath

自选。要在其中创建文件的目录的路径。如果省略目录路径，则会在指定的共享中创建该文件。

如果指定了目录，则必须先存在于共享中，然后才能创建该文件。


   myfile

要创建的文件的名称。

有关路径命名限制的信息，请参阅名称和引用共享、目录、文件和元数据。

URI 参数

可以在请求 URI 上指定以下附加参数：


   x-ms-version

所有授权请求都是必需的。指定要用于此请求的操作的版本。在版本 2025-05-05 及更高版本中支持此作，以启用 NFS 协议的文件共享。

有关详细信息，请参阅 azure 存储服务版本控制。


    Content-Length

指定在请求正文中传输的字节数。版本 2019-02-02-02 至 2025-11-05：可选。如果存在，则必须为零。版本 2026-02-06 或更高版本：如果请求正文包含内容，则为必填。

如果没有任何内容且头部已被包含，则其值必须为零。如果头部指定


    x-ms-content-length

的文件大小小


    Content-Length

于，操作将失败，错误代码为 400。


    x-ms-content-length: byte value

必填。此标头指定文件的最大大小，最大大小为 4 字节（TiB）。


    Content-MD5

自选。支持版本为2026-02-06及更高版本。内容的 MD5 哈希。此哈希用于验证传输期间数据的完整性。当指定 Content-MD5 头时，Azure 文件会将已到达内容的哈希值与发送的头值进行比较。如果这两个哈希值不匹配，操作会失败，并显示错误代码 400（错误请求）。


    Content-Type

或


    x-ms-content-type

自选。文件的 MIME 内容类型。默认类型为


    application/octet-stream

。


    Content-Encoding

或


    x-ms-content-encoding

自选。指定哪些内容编码已应用于文件。当对文件资源执行获取文件作时，此值将返回到客户端，并且你可以使用它解码文件内容。


   Content-Language

或


   x-ms-content-language

自选。指定此资源使用的自然语言。


   Cache-Control

或


   x-ms-cache-control

自选。 Azure 文件存储此值，但不使用它或修改该值。


   x-ms-content-md5

自选。设置文件的 MD5 哈希。


   x-ms-content-disposition

自选。设置文件的


   Content-Disposition

标头。


   x-ms-type: file

必填。将此标头设置为


   file

。


   x-ms-meta-name:value

自选。与文件关联的名称/值对作为元数据。元数据名称必须遵循 C# 标识符的命名规则。

注意：无法从服务器消息块（SMB）客户端访问通过 Azure 文件指定的文件元数据。


   x-ms-file-creation-time: { now ¦ <DateTime> }

必需：版本 2019-02-02 到 2021-04-10。可选：版本 2021-06-08 及更高版本。文件的协调世界时（UTC）创建时间属性。可以使用

now

值来指示请求的时间。默认值为

now

。


   x-ms-file-last-write-time: { now ¦ <DateTime> }

必需：版本 2019-02-02 到 2021-04-10。可选：版本 2021-06-08 及更高版本。文件的协调世界时（UTC）最后一个写入属性。可以使用

now

值来指示请求的时间。默认值为

now

。


   x-ms-lease-id:<ID>

如果文件具有活动租约，则为必需。适用于版本 2019-02-02 及更高版本。

如果文件位于启用了 NFS 协议的文件共享上，则忽略此标头，这不支持文件租约。


   x-ms-client-request-id

自选。提供客户端生成的不透明值，该值具有配置日志记录时日志中记录的 1-kibibyte （KiB）字符限制。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。有关详细信息，请参阅监视 Azure 文件。


   x-ms-file-request-intent

如果需要


   Authorization

标头指定 OAuth 令牌。可接受的值为


   backup

。此标头指定，如果


   Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

或


   Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

包含在分配给使用


   Authorization

标头授权的标识的 RBAC 策略中，则应授予


   Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

。适用于版本 2022-11-02 及更高版本。


   x-ms-allow-trailing-dot: { <Boolean> }

自选。版本 2022-11-02 及更高版本。布尔值指定是否应剪裁请求 URL 中存在的尾随点。

如果目标位于启用了 NFS 协议的文件共享上，则默认支持尾随点，则忽略此标头。

有关详细信息，请参阅命名和引用共享、目录、文件和元数据。


   x-ms-structured-body

如果请求主体的消息格式是结构化的，则是必需的。该头部的值包含消息模式版本和属性。

目前，唯一支持的值是


   XSM/1.0; properties=crc64

，表示请求在编码消息中使用 crc64 校验和段。如果值与此不符，作将失败，错误代码400（错误请求）。如果请求中提供的内容与给定段的校验和不匹配，请求也会失败。适用于2026-06-06及更高版本。仅支持内容长度大于零的请求。


   x-ms-structured-content-length

如果请求主体的消息格式是结构化的，即在请求中指定，则为


   x-ms-structured-body

必要。该头的值是文件内容的长度，由于消息编码，它总是小于


   Content-Length

头值。

如果头部值与请求中提供的块内容长度不匹配，作将失败，错误代码400（错误请求）。适用于2026-06-06及更高版本。

仅 SMB 请求标头


   x-ms-file-change-time: { now ¦ <DateTime> }

自选。版本 2021-06-08 及更高版本。文件的协调世界时（UTC）更改时间属性，格式为 ISO 8601。可以使用

now

值来指示请求的时间。默认值为

now

。


   x-ms-file-permission: { inherit ¦ <SDDL> ¦ <binary> }

在版本 2019-02-02 到 2021-04-10 中，如果未指定


   x-ms-file-permission-key

，则需要此标头。从版本 2021-06-08 起，这两个标头都是可选的。此权限是在 base64 编码二进制安全描述符格式的安全描述符定义语言（SDDL）或版本（版本 2024-11-04 或更高版本）中指定的文件的安全描述符。可以指定要用于


   x-ms-file-permission-format

标头的格式。如果权限大小为 8 kibibytes（KiB）或更少，则可以使用此标头。否则，可以使用


   x-ms-file-permission-key

。如果指定标头，它必须具有所有者、组和自由访问控制列表（DACL）。可以传递


   inherit

的值，以便从父目录继承。


   x-ms-file-permission-format: { sddl ¦ binary }

自选。版本 2024-11-04 或更高版本。指定传入


   x-ms-file-permission

的值是采用 SDDL 还是二进制格式。如果


   x-ms-file-permission

设置为


   inherit

，则不应设置此标头。如果


   x-ms-file-permission

设置为除


   inherit

以外的任何其他值，并且未设置此标头，则使用


   sddl

的默认值。


   x-ms-file-permission-key: <PermissionKey>

在版本 2019-02-02 到 2021-04-10 中，如果未指定


   x-ms-file-permission

，则需要此标头。从版本 2021-06-08 起，这两个标头都是可选的。如果未指定两个标头，则


   inherit

的默认值用于


   x-ms-file-permission

标头。

可以通过调用


   Create Permission

API 来创建密钥。


   x-ms-file-attributes

必需：版本 2019-02-02 到 2021-04-10。可选：版本 2021-06-08 及更高版本。此标头包含要对文件设置的文件系统属性。有关详细信息，请参阅可用属性的列表。默认值为


    None

。


    x-ms-file-property-semantics: { New ¦ Restore }

自选。支持版本为2026-02-06及更高版本。默认值为

New

。


    Restore

语义调整如何将头部应用


    x-ms-file-permission

到文件上。当


    x-ms-file-permission

头部设置为


    inherit

时，这些语义不会影响文件权限。当使用头部指定


    x-ms-file-permission

特定权限时，

New

语义学使用默认的 win32 文件创建规则，并可能应用基于父目录权限的略有不同权限，而


    Restore

语义学则使用默认更新语义，并会严格按照指定方式分配权限。

New

语义上也会在文件中添加 Archive 属性，即使头部未指定


    x-ms-file-attributes

。

仅 NFS 请求标头


    x-ms-mode

自选。版本 2025-05-05 及更高版本。要对文件设置的模式位。模式以 12 位数字八进制格式或符号“rwx”格式表示。默认值为 0644。请参阅 POSIX 文件权限（模式）。


   x-ms-owner

自选。版本 2025-05-05 及更高版本。要对文件设置的文件所有者的用户标识符（UID）。默认值为 0（root）。


   x-ms-group

自选。版本 2025-05-05 及更高版本。要对文件设置的文件所有者的组标识符（GID）。默认值为 0（根组）。


   x-ms-file-file-type

自选。版本 2025-05-05 及更高版本。文件的类型。如果存在，则必须为“常规”。

没有 if Content-Length 等于零。如果 Content-Length 头部设置为非零，则是必需的。该功能支持2026-02-06版本及更新版本。请求主体和内容长度头部中指定的字节数必须相匹配，才能执行带数据创建文件的操作。请求体中最大可指定的字节数为4MiB。

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=  
带 Content-Length 头的示例请求
Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile HTTP/1.1  
Request Headers:  
x-ms-version: 2026-02-06
x-ms-date: Mon, 27 Jan 2014 22:41:55 GMT  
Content-Type: text/plain; charset=UTF-8  
x-ms-content-length: 1024
Content-Length: 512
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  
响应包括 HTTP 状态代码和一组响应标头。
成功的操作返回状态代码 201（已创建）。 有关状态代码的信息，请参阅 状态和错误代码。
此作的响应包括下表中的标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。
常见响应标头
Last-Modified
返回上次修改文件的日期和时间。 日期格式遵循 RFC 1123。 有关详细信息，请参阅 表示标头中的日期/时间值。

 修改目录或其属性的任何操作将更新上次修改时间。 对文件的操作不会影响目录的上次修改时间。
x-ms-request-id
唯一标识已发出的请求，并可用于对请求进行故障排除。 有关详细信息，请参阅 API作疑难解答
x-ms-version
指示用于执行请求的 Azure 文件版本。
由服务生成的 UTC 日期/时间值，该值指示启动响应的时间。
x-ms-request-server-encrypted: true/false
版本 2017-04-17 及更高版本。 如果已使用指定的算法成功加密请求的内容，则此标头的值将设置为 true。 如果加密失败，则该值 false。
x-ms-file-creation-time
表示文件的创建时间属性的 UTC 日期/时间值。
x-ms-file-last-write-time
表示文件的上次写入时间属性的 UTC 日期/时间值。
x-ms-file-change-time
表示文件的更改时间属性的值的 UTC 日期/时间。
x-ms-file-file-id
文件的文件 ID。
x-ms-file-parent-id
文件的父文件 ID。
Content-MD5
版本为2026-02-06及以后。 返回此标头，以便客户端可以检查消息内容完整性。 此标头的值由文件服务计算。
x-ms-client-request-id
用于对请求及其相应的响应进行故障排除。 如果此标头存在于请求中，则此标头的值等于 x-ms-client-request-id 标头的值，并且该值包含不超过 1,024 个可见 ASCII 字符。 如果请求中不存在 x-ms-client-request-id 标头，则响应中不存在该标头。
仅 SMB 响应标头
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  
只有帐户所有者才能调用此作。
文件系统属性
Win32 文件属性
“0644”或“rw-r--r--”：用户（文件所有者）具有读取、写入权限。 组具有读取权限。 其他人具有读取权限。
“0755”或“rwxr-xr-x”：用户（文件所有者）具有读取、写入和执行权限。 组具有读取和执行权限。 其他人具有读取和执行权限。
数字八进制格式
三个最低顺序八进制数表示所有者/用户、组和其他用户的权限，并使用八进制数（0-7）表示使用按位组合“4”（读取）、“2”（写入）、“1”（执行）。
最高阶八进制数（0-7）用于指示“4”（SetUID）、“2”（SetGID）、“1”（StickyBit）权限的组合。
若要创建新文件，请先通过调用 Create File 并指定其最大大小（最多 4 TiB）来初始化它。 执行此操作时，请不要在请求正文中包含内容。 创建文件后，调用 Put Range 将内容添加到文件或对其进行修改。
从2026-02-06版本及以后版本开始，你可以通过在请求主体中提供内容，创建数据最高可达4MiB的文件。 创建包含数据的文件后，调用 Put Range 添加更多数据或修改文件。 文件的最大大小可达4 TiB。
可以通过调用 Set File Properties来更改文件大小。
如果共享或父目录不存在，则该操作将失败，状态代码为 412（前置条件失败）。
文件属性 cache-control、content-type、content-md5、content-encoding和 content-language 独立于 SMB 客户端可用的文件系统属性。 SMB 客户端无法读取、写入或修改这些属性值。
若要创建该文件，如果现有文件具有活动租约，客户端必须在请求中指定有效的租约 ID。 如果客户端未指定租约 ID 或指定无效的租约 ID，Azure 文件将返回状态代码 412（前置条件失败）。 如果客户端指定租约 ID 但文件没有活动租约，则 Azure 文件在此实例中也返回状态代码 412（前置条件失败）。 如果客户端在尚不存在的文件上指定租约 ID，则 Azure 文件会针对针对版本 2019-02-02 及更高版本发出的请求返回状态代码 412（先决条件失败）。
如果具有活动租约的现有文件被 Create File作覆盖，则租约将保留在更新的文件上，直到它释放为止。
共享快照不支持 Create File，这是共享的只读副本。 尝试对共享快照执行此操作失败，状态代码为 400（InvalidQueryParameterValue）。
对文件 作