重命名文件

Rename File作将重命名文件，并且可以选择为该文件设置系统属性。 此 API 在版本 2021-04-10 及更高版本中提供。

协议可用性

已启用文件共享协议	可用
SMB
NFS

请求

Rename File 请求构造如下。 建议使用 HTTPS。

方法	请求 URI	HTTP 版本
放	https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rename	HTTP/1.1

将请求 URI 中显示的路径组件替换为你自己的路径组件，如下所示：

路径组件	描述
myaccount	存储帐户的名称。
myshare	文件共享的名称。
mydirectorypath	自选。 父目标目录的路径。
myfile	目标文件的名称。

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

URI 参数

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

参数	描述
timeout	自选。 timeout 参数以秒为单位表示。 有关详细信息，请参阅 设置 Azure 文件存储作的超时。

请求标头

下表描述了必需和可选的请求标头。

请求标头	描述
Authorization	必填。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅 授权对 Azure 存储的请求。
Date 或 x-ms-date	必填。 指定请求的协调世界时（UTC）。 有关详细信息，请参阅 授权对 Azure 存储的请求。
x-ms-version	所有授权请求都是必需的。 指定要用于此请求的操作的版本。 有关详细信息，请参阅 azure 存储服务 版本控制。
x-ms-file-rename-source:name	必填。 要重命名的文件的完整 URI。
x-ms-file-rename-replace-if-exists	自选。 如果目标文件已存在，请覆盖该文件。
x-ms-file-rename-ignore-readonly	自选。 如果目标文件存在 readonly 属性，请覆盖该文件。 如果为 true，则 x-ms-file-rename-replace-if-exists 也必须为 true。
x-ms-content-Type	自选。 设置文件的内容类型。 如果未在请求中指定此属性，则将保留该文件的属性。
x-ms-file-permission: { preserve ¦ <SDDL> ¦ <binary> }	如果未指定 x-ms-file-permission-key，则为可选。 此权限是 base64 编码 二进制安全描述符格式中 安全描述符定义语言（SDDL） 中指定的文件的安全描述符（版本 2024-11-04 或更高版本）。 可以指定要用于 x-ms-file-permission-format 标头的格式。 如果权限大小为 8 kibibytes（KiB）或更少，则可以使用此标头。 否则，可以使用 x-ms-file-permission-key。 如果指定，则此权限必须具有所有者、组和 自由访问控制列表。 如果要保持现有值不变，可以传递 preserve 的值。 请注意，可以指定 x-ms-file-permission 或 x-ms-file-permission-key，而不是同时指定两者。
x-ms-file-permission-format: { sddl ¦ binary }	自选。 版本 2024-11-04 或更高版本。 指定传入 x-ms-file-permission 的值是采用 SDDL 还是二进制格式。 如果 x-ms-file-permission 设置为 preserve，则不应设置此标头。 如果 x-ms-file-permission 设置为除 preserve之外的任何其他值，并且未设置此标头，则使用 sddl 的默认值。
x-ms-file-permission-key	如果未指定 x-ms-file-permission，则为可选。 要为文件设置的权限的键。 可以使用 Create-Permission API 创建此内容。 请注意，可以指定 x-ms-file-permission 或 x-ms-file-permission-key，而不是同时指定两者。
x-ms-file-attributes	自选。 要对文件设置的文件系统属性。 请参阅 可用属性的列表。 如果要保持现有值不变，可以传递 preserve 的值。 如果未在请求中指定此属性，则将保留该文件的属性。
x-ms-file-creation-time	自选。 文件的 UTC 创建时间属性。 如果要保持现有值不变，可以传递 preserve 的值。 如果未在请求中指定此属性，则将保留该文件的属性。
x-ms-file-last-write-time	自选。 文件的 UTC 上次写入属性。 如果要保持现有值不变，可以传递 preserve 的值。 如果未在请求中指定此属性，则将保留该文件的属性。
x-ms-source-lease-id:<ID>	如果源文件具有活动租约，则为必需。
x-ms-destination-lease-id:<ID>	如果目标文件具有活动租约，则为必需。
x-ms-client-request-id	自选。 提供客户端生成的不透明值，该值具有配置日志记录时日志中记录的 1-kibibyte （KiB） 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息，请参阅 监视 Azure Blob 存储。
x-ms-meta-name:value	自选。 设置文件的名称/值对。 每次调用此操作都会替换附加到文件的所有现有元数据。 元数据名称必须遵循 C# 标识符的命名规则。
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 中存在的尾随点。 有关详细信息，请参阅 命名和引用共享、目录、文件和元数据。
x-ms-source-allow-trailing-dot: { <Boolean> }	自选。 版本 2022-11-02 及更高版本。 布尔值指定是否应剪裁源 URL 中存在的尾随点。 仅当复制源是 Azure 文件时，才应指定此标头。 任何其他复制源类型都不支持此标头。 有关详细信息，请参阅 命名和引用共享、目录、文件和元数据。

请求正文

没有。

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

成功的操作返回状态代码 200（正常）。 有关状态代码的信息，请参阅 状态和错误代码。

响应标头

此作的响应包括下表中的标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。

响应标头	描述
ETag	包含一个值，该值代表文件的版本，以引号表示。
Last-Modified	返回上次修改文件的日期和时间。 有关详细信息，请参阅 标头中的日期/时间值的表示形式。 修改目录或其属性的任何操作都更新上次修改时间。 对文件的操作不会影响目录的上次修改时间。
x-ms-request-id	唯一标识已发出的请求，并可用于对请求进行故障排除。 有关详细信息，请参阅 API作故障排除。
x-ms-version	指示用于运行请求的 Azure 文件的版本。
Date 或 x-ms-date	一个 UTC 日期/时间值，指示响应的启动时间。 服务将生成此值。
x-ms-request-server-encrypted: true/false	如果请求的内容通过使用指定的算法成功加密，则此标头的值将设置为 true。 否则，该值设置为 false。
x-ms-file-permission-key	文件权限的密钥。
x-ms-file-attributes	文件上的文件系统属性。 请参阅 可用属性的列表。
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。
x-ms-client-request-id	可用于对请求和相应的响应进行故障排除。 此标头的值等于 x-ms-client-request-id 标头的值（如果请求中存在）。 该值最多为 1,024 个可见 ASCII 字符。 如果请求中不存在 x-ms-client-request-id 标头，则响应中不会显示该标头。

响应正文

没有。

授权

只有帐户所有者才能调用此作。

文件系统属性

属性	Win32 文件属性	定义
ReadOnly	FILE_ATTRIBUTE_READONLY	只读文件。 应用程序可以读取文件，但无法写入文件或删除该文件。
Hidden	FILE_ATTRIBUTE_HIDDEN	文件已隐藏。 它不包括在普通目录列表中。
System	FILE_ATTRIBUTE_SYSTEM	操作系统使用部分或独占使用的文件。
None	FILE_ATTRIBUTE_NORMAL	未设置其他属性的文件。 此属性仅在单独使用时才有效。
Archive	FILE_ATTRIBUTE_ARCHIVE	作为存档文件的文件。 应用程序通常使用此属性标记文件以供备份或删除。
Temporary	FILE_ATTRIBUTE_TEMPORARY	用于临时存储的文件。
Offline	FILE_ATTRIBUTE_OFFLINE	文件的数据不会立即可用。 此文件系统属性主要用于提供与 Windows 的兼容性。 Azure 文件存储不支持脱机存储选项。
NotContentIndexed	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED	文件不会由内容索引服务编制索引。
NoScrubData	FILE_ATTRIBUTE_NO_SCRUB_DATA	用户数据流不会由后台数据完整性扫描程序读取。 此文件系统属性主要用于提供与 Windows 的兼容性。

言论

目标不能是现有目录。

如果未指定属性，将设置 preserve 或 now 的默认行为。

注意

上述文件属性独立于可用于 SMB 客户端的文件系统属性。 SMB 客户端无法读取、写入或修改这些属性值。

共享快照不支持 Rename File，这是共享的只读副本。 如果尝试对共享快照执行此操作，服务将返回错误状态 400（查询参数值无效）。

如果文件具有活动租约，客户端必须在请求上指定有效的租约 ID 才能重命名文件。 如果客户端未指定租约 ID 或指定无效的租约 ID，Azure 文件将返回状态代码 412（前置条件失败）。 如果客户端指定租约 ID，但文件没有活动租约，Azure 文件也返回状态代码 412（前置条件失败）。

另请参阅

对文件 作