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

重命名文件

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 存储的请求。
Datex-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-permissionx-ms-file-permission-key,而不是同时指定两者。
x-ms-file-permission-format: { sddl ¦ binary } 自选。 版本 2024-11-04 或更高版本。 指定传入 x-ms-file-permission 的值是采用 SDDL 还是二进制格式。 如果 x-ms-file-permission-key 设置为 preserve,则不应设置此标头。 如果 x-ms-file-permission-key 设置为除 preserve之外的任何其他值,并且未设置此标头,则使用 sddl 的默认值。
x-ms-file-permission-key 如果未指定 x-ms-file-permission,则为可选。 要为文件设置的权限的键。 可以使用 Create-Permission API 创建此内容。

请注意,可以指定 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-kibibyte (KiB) 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅 监视 Azure Blob 存储
x-ms-meta-name:value 自选。 设置文件的名称/值对。

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

元数据名称必须遵循 C# 标识符的命名规则。
x-ms-file-request-intent 如果需要 Authorization 标头指定 OAuth 令牌。 可接受的值为 backup。 此标头指定,如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.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 文件的版本。
Datex-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 的兼容性。

言论

目标不能是现有目录。

如果未指定属性,将设置 preservenow 的默认行为。

注意

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

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

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

另请参阅

对文件 操作