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

设置文件属性

  • 项目

Set File Properties操作可设置文件的系统属性。

协议可用性

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

请求

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

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

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

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

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

URI 参数

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

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

请求标头

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

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅授权对 Azure 存储的请求。
Date 或 x-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息，请参阅授权对 Azure 存储的请求。
x-ms-version 对于所有已授权的请求是必需的。 指定用于此请求的操作的版本。 有关详细信息，请参阅 Azure 存储服务的版本控制。
x-ms-cache-control 可选。 修改文件的缓存控制字符串。

如果未在请求中指定此属性，则会为文件清除 该属性。 对 “获取文件属性” 的后续调用不会返回此属性，除非再次在文件上显式设置此属性。
x-ms-content-type 可选。 设置文件的内容类型。

如果未在请求中指定此属性，则会为文件清除 该属性。 对 “获取文件属性” 的后续调用不会返回此属性，除非再次在文件上显式设置此属性。
x-ms-content-md5 可选。 设置文件的 MD5 哈希。

如果未在请求中指定此属性，则会为文件清除 该属性。 对 “获取文件属性” 的后续调用不会返回此属性，除非再次在文件上显式设置此属性。
x-ms-content-encoding 可选。 设置文件的内容编码。

如果未在请求中指定此属性，则会为文件清除 该属性。 对 “获取文件属性” 的后续调用不会返回此属性，除非再次在文件上显式设置此属性。
x-ms-content-language 可选。 设置文件的内容语言。

如果未在请求中指定此属性，则会为文件清除 该属性。 对 “获取文件属性” 的后续调用不会返回此属性，除非再次在文件上显式设置此属性。
x-ms-content-disposition 可选。 设置文件的 Content-Disposition 标头。

如果未在请求中指定此属性，则会为文件清除 该属性。 对 “获取文件属性” 的后续调用不会返回此属性，除非再次在文件上显式设置此属性。
x-ms-content-length: bytes 可选。 将文件调整为指定大小。 如果指定的字节值小于文件的当前大小，则会清除指定字节值上方的所有区域。
x-ms-file-permission: { preserve ¦ <SDDL> } 在版本 2019-02-02 到 2021-04-10 中，如果未 x-ms-file-permission-key 指定，则需要此标头。 从版本 2021-06-08 起，这两个标头都是可选的。 此权限是安全描述符 定义语言 (SDDL) 中指定的文件的安全描述符 。 如果权限大小为 8 kiB () 或更小，则可以使用此标头。 否则，可以使用 x-ms-file-permission-key。 如果指定，它必须具有所有者、组和 可自由访问控制列表 (DACL) 。 可以传递 值 preserve 以保持现有值不变。

注意：可以指定 x-ms-file-permission 或 x-ms-file-permission-key。 如果未指定这两个标头，则使用 的 preserve 默认值。
x-ms-file-permission-key: <PermissionKey> 在版本 2019-02-02 到 2021-04-10 中，如果未 x-ms-file-permission 指定，则需要此标头。 从版本 2021-06-08 起，这两个标头都是可选的。 要为文件设置的权限的键。 这可以使用 API 创建 Create-Permission 。

注意：可以指定 x-ms-file-permission 或 x-ms-file-permission-key。 如果未指定两个标头，则 的默认值 preserve 将用于 x-ms-file-permission 标头。
x-ms-file-attributes: { preserve ¦ <FileAttributeList> } 必需版本 2019-02-02 到 2021-04-10。 可选版本 2021-06-08 及更高版本。 要对文件设置的文件系统属性。 请参阅 可用属性列表。 可以传递 值 preserve 以保持现有值不变。 默认值为 preserve。
x-ms-file-creation-time: { preserve ¦ <DateTime> } 必需版本 2019-02-02 到 2021-04-10。 可选版本 2021-06-08 及更高版本。 文件的协调世界时 (UTC) 创建时间属性。 可以传递 值 preserve 以保持现有值不变。 默认值为 preserve。
x-ms-file-last-write-time: { preserve ¦ <DateTime> } 必需，版本 2019-02-02 到 2021-04-10。 可选，版本 2021-06-08 及更高版本。 协调世界时 (UTC) 文件的上次写入属性。 可以传递 值 preserve 以保持现有值不变。 如果 preserve 指定 了 并且文件的大小已更改，则上次写入时间将更新为当前时间。 如果更改了文件大小，但提供了显式时间戳，则使用显式时间戳。 默认值为 preserve。
x-ms-lease-id: <ID> 如果文件具有活动租约，则为必需。 适用于版本 2019-02-02 及更高版本。
x-ms-client-request-id 可选。 提供客户端生成的不透明值，其中包含 1-kibite (KiB) 配置日志记录时记录在日志中的字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息，请参阅监视Azure 文件存储。
x-ms-file-change-time: { now ¦ <DateTime> } 可选。 版本 2021-06-08 及更高版本。 协调世界时 (UTC) 更改文件的时间属性，格式为 ISO 8601。 可以使用 值 now 来指示请求的时间。 默认值为 now。
x-ms-file-request-intent 如果 Authorization 标头指定 OAuth 令牌，则为必需。 可接受的值为 backup。 此标头指定Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action如果或包含在分配给使用 标头授权的标识的 RBAC 策略中，则应授予 或 Authorization 。 适用于版本 2022-11-02 及更高版本。
x-ms-allow-trailing-dot: { <Boolean> } 可选。 版本 2022-11-02 及更高版本。 布尔值指定是否应剪裁请求 URL 中存在的尾随点。 有关详细信息，请参阅 命名和引用共享、目录、文件和元数据。

请求正文

无。

响应

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

状态代码

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

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

响应头

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

响应标头 说明
ETag 包含一个值，该值表示文件的版本。 该值用引号引起来。
Last-Modified 返回上次修改文件的日期和时间。 日期格式遵循 RFC 1123。 有关详细信息，请参阅 在标头中表示日期/时间值。 修改目录或其属性的任何操作会更新上次修改的时间。 对文件执行的操作不会影响目录的上次修改时间。
x-ms-request-id 唯一标识发出的请求，可用于对请求进行故障排除。 有关详细信息，请参阅 API 操作疑难解答。
x-ms-version 指示用于执行请求的文件服务的版本。
Date 或 x-ms-date 由服务生成的 UTC 日期/时间值，指示启动响应的时间。
x-ms-request-server-encrypted: true/false 版本 2017-04-17 及更高版本。 如果使用指定的算法成功加密请求的内容，则此标头的值设置为 true 。 否则，该值将设置为 false。
x-ms-file-permission-key 版本 2019-02-02 及更高版本。 文件权限的键。
x-ms-file-attributes 版本 2019-02-02 及更高版本。 文件上的文件系统属性。 有关详细信息，请参阅 可用属性列表。
x-ms-file-creation-time 版本 2019-02-02 及更高版本。 表示文件的创建时间属性的 UTC 日期/时间值。
x-ms-file-last-write-time 版本 2019-02-02 及更高版本。 表示文件的上次写入时间属性的 UTC 日期/时间值。
x-ms-file-change-time 版本 2019-02-02 及更高版本。 表示文件的更改时间属性的 UTC 日期/时间值。
x-ms-client-request-id 可用于对请求和相应的响应进行故障排除。 如果请求中存在标头， x-ms-client-request-id 并且该值包含的可见 ASCII 字符不超过 1,024 个，则此标头的值等于标头的值。 x-ms-client-request-id如果请求中不存在标头，则响应中不会显示该标头。

响应正文

无。

授权

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

文件系统属性

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

注解

更新文件属性的语义如下所示：

  • 只有在请求指定了 x-ms-content-length 标头值时，才会修改文件的大小。

  • 如果请求仅 x-ms-content-length 设置其他属性，则不会修改文件的其他属性。

  • 如果在请求中设置了以下任何一个或多个属性，则所有这些属性将一起设置。 如果在至少设置了以下属性之一时未为指定属性提供值，则会为文件清除该属性。

    • x-ms-cache-control
    • x-ms-content-type
    • x-ms-content-md5
    • x-ms-content-encoding
    • x-ms-content-language

注意

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

Set File properties共享快照（共享的只读副本）上不受支持。 尝试对共享快照执行此操作失败，) 为 400 (InvalidQueryParameterValue。

如果文件具有活动租约，则客户端必须在请求中指定有效的租约 ID，以便将属性写入文件。 如果客户端未指定租约 ID 或指定无效租约 ID，则文件服务将返回状态代码 412 (先决条件失败) 。 如果客户端指定租约 ID，但文件没有活动租约，则文件服务还会返回状态代码 412 (前置条件失败) 。

另请参阅

Azure 文件存储 上的操作