你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

重命名文件

Rename File 操作将重命名文件,并且可以选择性地为文件设置系统属性。 此 API 从版本 2021-04-10 开始提供。

协议可用性

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

请求

可以按如下方式构建Rename File请求。 建议使用 HTTPS。

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

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

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

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

URI 参数

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

参数 说明
timeout 可选。 timeout 参数以秒表示。 有关详细信息,请参阅 设置文件服务操作的超时

请求标头

下表介绍必需的和可选的请求标头。

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅授权请求Azure 存储
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权请求Azure 存储
x-ms-version 所有已授权请求都是必需的。 指定用于此请求的操作的版本。 有关详细信息,请参阅Azure 存储服务的版本控制
x-ms-file-rename-source:name 必需。 要重命名的文件的名称。
x-ms-file-rename-replace-if-exists 可选。 如果目标文件已存在,请覆盖该文件。
x-ms-file-ignore-readonly 可选。 如果目标文件存在具有只读属性,请覆盖该文件。

如果为 true, x-ms-replace-if-exists 则还必须为 true。
x-ms-content-Type 可选。 设置文件的内容类型。

如果未在请求上指定此属性,则将为文件保留该属性
x-ms-file-permission 如果未指定 x-ms-file-permission-key,则是可选的。 此权限是 安全描述符定义语言 (SDDL) 中指定的文件的安全描述符。 如果权限大小超过 8 KiB,则可以使用此标头,否则 x-ms-file-permission-key 可以使用该标头。 如果指定,它必须具有所有者、组和 自由访问控制列表 (DACL) 。 可能会传递一 preserve 个值,以使现有值保持不变。

请注意,只能指定其中一个 x-ms-file-permissionx-ms-file-permission-key 可以指定。
x-ms-file-permission-key 如果未指定 x-ms-file-permission,则是可选的。 要为文件设置的权限的密钥。 这可以使用 API 创建 Create-Permission

请注意,只能指定其中一个 x-ms-file-permissionx-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 KiB 字符限制,在启用存储分析日志记录时记录在分析日志中。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅 监视 Azure Blob 存储
x-ms-meta-name:value 可选。 为文件设置名称-值对。

每次调用此操作都会替换附加到该文件的所有现有元数据。

元数据名称必须遵循 C# 标识符的命名规则。

请求正文

无。

响应

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

状态代码

此操作成功后返回状态代码 200(正常)。

有关状态代码的信息,请参阅 “状态”和“错误代码”。

响应头

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

响应标头 说明
ETag ETag 包含表示文件版本的值,该值括在引号中。
Last-Modified 返回上次修改文件的日期和时间。 日期格式遵循 RFC 1123。 有关详细信息,请参阅 标头中Date-Time值的表示形式。 修改目录或其属性的任何操作都将更新上次修改时间。 对文件执行的操作不会影响目录的上次修改时间。
x-ms-request-id 此标头唯一地标识发出的请求,并且可用于解决请求问题。 有关详细信息,请参阅 API 操作疑难解答
x-ms-version 指示用于执行请求的文件服务的版本。
Datex-ms-date 服务生成的 UTC 日期/时间值指示启动响应的时间。
x-ms-request-server-encrypted: true/false 如果请求的内容使用指定的算法成功加密,则false此标头的值设置为true否则为 。
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 ,并且该值最多为 1024 个可见 ASCII 字符。 x-ms-client-request-id如果请求中不存在标头,则响应中将不会显示此标头。

响应正文

无。

授权

只有帐户所有者可以调用此操作。

文件系统属性

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

备注

目标不能是现有目录。

如果未指定属性,则设置或now将设置 defualt 行为preserve

注意

上面列出的文件属性与可用于 SMB 客户端的文件系统属性不同。 SMB 客户端不能读取、写入或修改这些属性值。

Rename File 共享快照不支持,这是共享的只读副本。 尝试对共享快照执行此操作会失败, (InvalidQueryParameterValue) 400。

如果文件具有活动租约,客户端必须在请求中指定有效的租约 ID 才能重命名该文件。 如果客户端未指定租约 ID 或指定无效的租约 ID,则文件服务将返回状态代码 412 (前置条件失败) 。 如果客户端指定租约 ID,但文件没有活动租约,则文件服务还会返回状态代码 412 (前置条件失败) 。

请参阅

对文件的操作