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

Path - Update

Service:

Storage Services

API Version:

2023-08-03

追加数据 |刷新数据 |设置属性 |设置访问控制
上传要追加到文件的数据，刷新 () 之前上传的数据写入文件，设置文件或目录的属性，或设置文件或目录的访问控制。 数据只能追加到文件。 不支持使用多个客户端对同一文件进行并发写入。 此操作支持条件 HTTP 请求。 有关详细信息，请参阅为 Blob 服务操作指定条件标头。

PATCH https://{accountName}.{dnsSuffix}/{filesystem}/{path}?action={action}

With optional parameters:

PATCH https://{accountName}.{dnsSuffix}/{filesystem}/{path}?action={action}&position={position}&retainUncommittedData={retainUncommittedData}&close={close}&mode={mode}&maxRecords={maxRecords}&forceFlag={forceFlag}&continuation={continuation}&flush={flush}&timeout={timeout}

URI 参数

名称	在	必需	类型	说明
accountName	path	True	string	Azure 存储帐户名称。
dnsSuffix	path	True	string	Azure Data Lake Storage终结点的 DNS 后缀。
filesystem	path	True	string	文件系统标识符。 Regex pattern: ^[$a-z0-9](?!.*--)[-a-z0-9]{1,61}[a-z0-9]$
path	path	True	string	文件或目录路径。
action	query	True	PathUpdateAction	操作必须“追加”才能上传要追加到文件的数据，“刷新”操作将以前上传的数据刷新到文件，“setProperties”设置文件或目录的属性，或“setAccessControl”设置文件或目录的所有者、组、权限或访问控制列表，或“setAccessControlRecursive”以递归方式设置目录的访问控制列表。 请注意，必须为帐户启用分层命名空间才能使用访问控制。 另请注意，访问控制列表 (ACL) 包括所有者、拥有组和其他人员的权限，因此 x-ms-permissions 和 x-ms-acl 请求标头是互斥的。
close	query		boolean	Azure 存储事件允许应用程序在文件更改时接收通知。 启用 Azure 存储事件后，将引发文件更改事件。 此事件具有一个属性，指示这是否是最终更改，以区分文件流的中间刷新与文件流最终关闭之间的差异。 仅当操作为“刷新”并启用更改通知时，close 查询参数才有效。 如果 close 的值为“true”并且刷新操作成功完成，则服务会引发文件更改通知，其中包含一个属性，指示这是 (文件流) 关闭的最终更新。 如果“false”，则会引发更改通知，指示文件已更改。 默认值为 false。 Hadoop ABFS 驱动程序将此查询参数设置为 true，以指示文件流已关闭。”
continuation	query		string	可选且仅适用于“setAccessControlRecursive”操作。 每次调用时处理的路径数是有限的。 如果要处理的路径数超过此限制，则会在响应标头 x-ms-continuation 中返回延续标记。 在响应中返回延续标记时，它必须百分比编码，并在 setAccessControlRecursive 操作的后续调用中指定。
flush	query		boolean	仅对追加调用有效。 此参数允许调用方在追加调用期间刷新。 默认值为“false”，如果为“true”，则使用追加调用刷新数据。 请注意，使用 flush=true 时，不支持以下标头 -“x-ms-cache-control”、“x-ms-content-encoding”、“x-ms-content-type”、“x-ms-content-language”、“x-ms-content-md5”、“x-ms-content-disposition”。 若要在刷新期间设置这些标头，请使用 action=flush
forceFlag	query		boolean	可选且仅适用于“setAccessControlRecursive”操作。 如果此为“false”，则遇到用户错误 (4XX) 时，操作将快速终止。 如果为“true”，则 API 将忽略用户错误，并继续对目录的其他子实体执行操作。 用户错误的详细状态将在任一方案的响应中返回。 只有在发生用户错误时 forceFlag 为“true”时，才会返回延续标记。 forceFlag 的默认值为 false。
maxRecords	query		integer int32	可选且仅适用于“setAccessControlRecursive”操作。 它指定将应用 acl 更改的最大文件或目录数。 如果省略或大于 2,000，则请求将处理最多 2,000 个项目
mode	query		string	可选。 “setAccessControlRecursive”操作有效且必需。 模式“set”设置对文件和目录的 POSIX 访问控制权限，“修改”修改文件和目录上预先存在的一个或多个 POSIX 访问控制权限，“删除”将删除文件和目录上先前存在的一个或多个 POSIX 访问控制权限
position	query		integer int64	此参数允许调用方并行上传数据，并控制数据追加到文件的顺序。 上传要追加到文件的数据以及将以前上传的数据刷新到该文件时，都需要它。 值必须是要追加数据的位置。 上传的数据不会立即刷新或写入文件。 若要刷新，以前上传的数据必须是连续的，必须指定位置参数，并且必须在写入所有数据后等于文件的长度，并且请求中不得包含请求实体正文。
retainUncommittedData	query		boolean	仅对刷新操作有效。 如果为“true”，则刷新操作完成后保留未提交的数据;否则，刷新操作后会删除未提交的数据。 默认值为 false。 刷新成功时，偏移量小于指定位置的数据将写入文件，但此可选参数允许保留刷新位置后的数据以供将来的刷新操作使用。
timeout	query		integer int32	可选的操作超时值（以秒为单位）。 时间段从服务接收请求时开始。 如果超时值在操作完成之前已过，则操作将失败。

请求头

Media Types: "application/octet-stream", "text/plain"

名称	必需	类型	说明
Content-Length		integer int64	“追加数据”和“刷新数据”是必需的。 对于“刷新数据”，必须为 0。 必须为“追加数据”的请求内容的长度（以字节为单位）。
Content-MD5		string	可选。 请求内容的 MD5 哈希值。 此标头在“追加”和“刷新”操作上有效。 此哈希值用于验证传输期间请求内容的完整性。 指定此标头时，存储服务会对已到达内容的哈希值与此标头值进行比较。 如果这两个哈希值不匹配，操作会失败，并显示错误代码 400（错误请求）。 请注意，此 MD5 哈希不随 文件一起存储。 此标头与请求内容相关联，而不是与文件本身的存储内容相关联。
x-ms-lease-id		string	如果存在活动租约，则必须指定租约 ID。 对于“setAccessControlRecursive”操作无效。 Regex pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-cache-control		string	可选，仅对刷新和设置属性操作有效。 服务存储此值，并将其包含在“读取文件”操作的“Cache-Control”响应标头中。
x-ms-content-type		string	可选，仅对刷新和设置属性操作有效。 该服务存储此值，并将其包含在“读取文件”操作的“Content-Type”响应标头中。
x-ms-content-disposition		string	可选，仅对刷新和设置属性操作有效。 该服务存储此值，并将其包含在“读取文件”操作的“Content-Disposition”响应标头中。
x-ms-content-encoding		string	可选，仅对刷新和设置属性操作有效。 服务存储此值，并将其包含在“读取文件”操作的“Content-Encoding”响应标头中。
x-ms-content-language		string	可选，仅对刷新和设置属性操作有效。 该服务存储此值，并将其包含在“Read File”操作的“Content-Language”响应标头中。
x-ms-content-md5		string	可选，仅对“刷新和设置属性”操作有效。 服务存储此值，并将其包含在“读取和获取属性”操作的“Content-Md5”响应标头中。 如果没有指定请求的此属性，则会为文件清除该属性。 对“读取和获取属性”的后续调用不会返回此属性，除非再次在该文件上显式设置此属性。
x-ms-properties		string	可选。 要与文件或目录一起存储的用户定义的属性，格式为逗号分隔的名称和值对列表“n1=v1，n2=v2，...”，其中每个值都是 base64 编码字符串。 请注意，字符串在 ISO-8859-1 字符集中只能包含 ASCII 字符。 仅对 setProperties 操作有效。 如果文件或目录存在，则将删除列表中未包含的任何属性。 如果省略标头，则删除所有属性。 若要合并新属性和现有属性，请先获取所有现有属性和当前 E-Tag，然后使用 E-Tag 发出条件请求，并包括所有属性的值。
x-ms-owner		string	可选且仅适用于 setAccessControl 操作。 设置文件或目录的所有者。
x-ms-group		string	可选且仅适用于 setAccessControl 操作。 设置文件或目录的拥有组。
x-ms-permissions		string	可选，仅当为帐户启用分层命名空间时有效。 设置文件所有者、文件拥有组和其他文件的 POSIX 访问权限。 每个类可以被授予读取 4) (、写入 (2) 或执行 (1) 权限。 支持符号 (rwxrw-rw-) 和 4 位八进制表示法 (例如 0766) 。 粘滞位也受支持，在符号表示法中，在最终字符位置由字母 t 或 T 表示，具体取决于其他类别的执行位是分别设置还是取消设置 (例如带有粘滞位的 rwxrw-rw- 表示为 rwxrw-rwT。带有粘滞位的 rwxrw-rwx 表示为 rwxrw-rwt) ，缺少 t 或 T 表示未设置粘滞位。 在 4 位八进制表示法中，它由第 1 位表示 (例如 1766 表示具有粘滞位的 rwxrw-rw-，0766 表示不带粘滞位的 rwxrw-rw-) 。 与 x-ms-acl 结合使用无效。
x-ms-acl		string	可选且仅适用于 setAccessControl 和 setAccessControlRecursive 操作。 setAccessControlRecursive 操作是必需的。 设置对文件和目录的 POSIX 访问控制权限。 该值是一个逗号分隔的访问控制项列表，在 setAccessControl 和 setAccessControlRecursive 的“set”模式的情况下，完全替换了现有访问控制列表 (ACL) 。 setAccessControlRecursive 的“modify”模式更新预先存在的 ACLS。 ACE) (每个访问控制项都由一个范围、一个类型、一个用户或组标识符以及格式为“[scope：][type]：[id]：[permissions]”的权限组成。 范围必须为“default”，以指示 ACE 属于目录的默认 ACL;否则，范围是隐式的，ACE 属于访问 ACL。 有四种 ACE 类型：“用户”向所有者或命名用户授予权限，“组”向拥有组或命名组授予权限，“掩码”限制授予命名用户和组成员的权限，“其他”向未在任何其他条目中找到的所有用户授予权限。 对于“mask”和“other”类型的条目，省略用户或组标识符。 对于所有者和拥有组，也会省略用户或组标识符。 权限字段是一个包含 3 个字符的序列，其中第一个字符为“r”以授予读取访问权限，第二个字符为“w”以授予写入访问权限，第三个字符为“x”以授予执行权限。 如果未授予访问权限，则使用“-”字符表示权限被拒绝。 例如，以下 ACL 向文件所有者和john.doe@contoso授予读取、写入和执行权限、对拥有组的读取权限，不授予其他所有人：“user：：rwx，user：john.doe@contoso：rwx，group：：r--,other：：---,mask=rwx”。 与 x-ms-permissions 一起无效。 setAccessControlRecursive 的“remove”模式会删除预先存在的 ACL，并且不应在指定的访问控制列表中包含权限：“user：john.doe@contoso：， mask：”。 setAccessControlRecursive 的“set”模式设置 ACL，该 ACL 替换指定范围的预先存在的 ACL，并且必须包含所有三个 - 拥有用户、拥有组和其他信息（如果访问范围已设置，或者如果拥有用户、拥有的组或其他权限正在默认范围内设置）。 setAccessControlRecursive 的“set”和“modify”模式必须包含作为访问控制列表一部分的权限。
If-Match		string	对于“刷新数据”、“设置访问控制”和“设置属性”是可选的，但对于“追加数据”和“设置访问控制递归”无效。 ETag 值。 指定此标头，以便仅在资源的 ETag 与指定的值匹配时才执行操作。 必须在引号中指定 ETag。
If-None-Match		string	对于“刷新数据”、“设置访问控制”和“设置属性”是可选的，但对于“追加数据”和“设置访问控制递归”无效。 ETag 值或特殊通配符 (“*”) 值。 指定此标头，以便仅在资源的 ETag 与指定的值不匹配时才执行操作。 必须在引号中指定 ETag。
If-Modified-Since		string	对于 Flush Data 和 Set 属性是可选的，但对于 Append Data 和 Set 访问控制递归无效。 日期和时间值。 指定此标头以仅当资源自指定日期和时间以来已修改时才执行操作。
If-Unmodified-Since		string	对于 Flush Data 和 Set 属性是可选的，但对于 Append Data 和 Set 访问控制递归无效。 日期和时间值。 指定此标头以仅当资源自指定日期和时间以来未修改时才执行操作。
x-ms-encryption-key		string	可选。 Base64 编码的 AES-256 加密密钥。
x-ms-encryption-key-sha256		string	可选。 加密密钥的 Base64 编码 SHA256 哈希。
x-ms-encryption-algorithm: AES256		string	可选。 指定要用于加密的算法。 此标头的值必须为 AES256。
x-ms-lease-action	True	PathLeaseAction	从追加和刷新操作的版本 2020-08-04 开始。 Append 支持“获取”、“自动续订”和“acquire-release”操作。 如果“获取”，它将获取租约。 如果“自动续订”，它将续订租约。 如果为“acquire-release”，它将获取 & 完成操作 & 在操作完成后释放租约。 “发布”操作仅在刷新操作中受支持。 如果为“true”，将使用 x-ms-lease-id 标头中的租约 ID 信息释放文件上的租约。
x-ms-lease-duration		integer int32	获取租约需要租约持续时间，并指定租约的持续时间（以秒为单位）。 租约持续时间必须介于 15 到 60 秒之间，对于无限租约，则为 -1。
x-ms-proposed-lease-id		string	当“x-ms-lease-action”为“acquire”或“change”时是必需的。 如果操作成功，将使用此租约 ID 获取租约。 Regex pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-client-request-id		string	用于故障排除和关联的分析日志中记录的 UUID。 Regex pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-date		string	指定请求的协调世界时 (UTC)。 使用共享密钥授权时，这是必需的。
x-ms-version		string	指定用于处理请求的 REST 协议的版本。 使用共享密钥授权时，这是必需的。

请求正文

Media Types: "application/octet-stream", "text/plain"

名称	类型	说明
requestBody	object	仅对追加操作有效。 要上传和追加到文件的数据。

响应

名称	类型	说明
200 OK	SetAccessControlRecursiveResponse	数据已刷新 (写入文件) 或属性设置成功。 响应正文是可选的，仅对“SetAccessControlRecursive”有效 Headers Date: string ETag: string Last-Modified: string Accept-Ranges: string Cache-Control: string Content-Disposition: string Content-Encoding: string Content-Language: string Content-Length: integer Content-Range: string Content-Type: string Content-MD5: string x-ms-properties: string x-ms-continuation: string x-ms-request-id: string x-ms-version: string x-ms-request-server-encrypted: true/false: boolean x-ms-encryption-key-sha256: string x-ms-encryption-scope: string x-ms-lease-renewed: boolean
202 Accepted		已接受上传的数据。 Headers Content-MD5: string Date: string x-ms-request-id: string x-ms-version: string x-ms-lease-renewed: boolean
Other Status Codes	DataLakeStorageError	出现了错误。 下面列出了可能的 HTTP 状态、代码和消息字符串： 400 错误的请求，ContentLengthMustBeZero，“Content-Length 请求标头必须为零。” 400 错误的请求，InvalidAuthenticationInfo，“未以正确的格式提供身份验证信息。 检查 Authorization 标头的值。” 400 错误的请求，InvalidFlushPosition，“上传的数据不是连续的，或者位置查询参数值不等于追加上传的数据后的文件长度。” 400 错误的请求，InvalidHeaderValue，“其中一个 HTTP 标头的值的格式不正确。” 400 错误的请求，InvalidHttpVerb，“指定的 HTTP 谓词无效 - 服务器无法识别它。” 400 错误的请求，InvalidInput，“其中一个请求输入无效。” 400 错误的请求，InvalidPropertyName，“属性名称不能为空。” 400 错误的请求，InvalidPropertyName，“属性名称包含无效字符。” 400 错误请求，InvalidQueryParameterValue，“请求 URI 中指定的某个查询参数的值无效。” 400 错误的请求，InvalidResourceName，“指定的资源名称包含无效字符。” 400 错误请求，InvalidSourceUri，“源 URI 无效。 400 错误的请求，InvalidUri，“请求 URI 无效。 400 错误请求，MissingRequiredHeader，“未指定此请求必需的 HTTP 标头。” 400 错误请求，MissingRequiredQueryParameter，“未指定此请求必需的查询参数。” 400 错误的请求，MultipleConditionHeadersNotSupported，“不支持多个条件标头。” 400 错误的请求，OutOfRangeInput，“其中一个请求输入超出范围。” 400 错误请求，OutOfRangeQueryParameterValue，“请求 URI 中指定的查询参数之一超出了允许的范围。” 400 错误的请求，UnsupportedHeader，“不支持请求中指定的标头之一。” 400 错误请求，UnsupportedQueryParameter，“不支持请求 URI 中指定的查询参数之一。” 400 错误的请求，UnsupportedRestVersion，“指定的 Rest 版本不受支持。” 403 禁止访问，AccountIsDisabled，“指定的帐户已禁用。” 403 禁止，AuthorizationFailure，“此请求无权执行此操作。” 403 禁止访问，InsufficientAccountPermissions，“正在访问的帐户没有足够的权限来执行此操作。” 404 未找到，FilesystemNotFound，“指定的文件系统不存在。” 404 找不到，PathNotFound，“指定的路径不存在。” 404 Not Found，RenameDestinationParentPathNotFound，“目标路径的父目录不存在。” 404 找不到，ResourceNotFound，“指定的资源不存在。” 404 Not Found， SourcePathNotFound， “重命名操作的源路径不存在。” 405 方法不允许，不支持HttpVerb，“资源不支持指定的 HTTP 谓词。” 409 Conflict，DestinationPathIsBeingDeleted，“指定的目标路径标记为要删除。” 409 Conflict， DirectoryNotEmpty， “递归查询参数值必须为 true 才能删除非空目录。” 409 Conflict，FilesystemAlreadyExists，“指定的文件系统已存在。” 409 Conflict， FilesystemBeingDeleted， “指定的文件系统正在删除。” 409 Conflict， InvalidDestinationPath， “指定的路径或路径的元素存在，并且其资源类型对于此操作无效。”* 409 冲突，InvalidFlushOperation，“资源由 Blob 服务 API 创建或修改，无法由Data Lake Storage服务 API 写入。” 409 冲突，InvalidRenameSourcePath，“源目录不能与目标目录相同，目标目录也不能是源目录的子目录。” 409 Conflict，InvalidSourceOrDestinationResourceType，“源和目标资源类型必须相同。” 409 Conflict， LeaseAlreadyPresent，“已存在租约。 409 Conflict， LeaseIdMismatchWithLeaseOperation，“指定的租约 ID 与具有指定租约操作的资源的租约 ID 不匹配。” 409 Conflict， LeaseIsAlreadyBroken， “租约已被打破， 不能再次打破。 409 Conflict， LeaseIsBreakingAndCannotBeAcquired，“租约 ID 匹配，但租约当前处于中断状态，在中断之前无法获取。” 409 Conflict， LeaseIsBreakingAndCannotBeChanged，“租约 ID 匹配，但租约当前处于中断状态，无法更改。” 409 Conflict， LeaseIsBrokenAndCannotBeRenewed，“租约 ID 匹配，但租约已显式中断，无法续订。” 409 Conflict， LeaseNameMismatch， “指定的租约名称与现有租约名称不匹配。” 409 Conflict， LeaseNotPresentWithLeaseOperation，“指定的租约操作中不存在租约 ID。 409 Conflict，PathAlreadyExists，“指定的路径已存在。” 409 Conflict， PathConflict， “指定的路径或路径的元素存在，并且其资源类型对于此操作无效。” 409 Conflict， SourcePathIsBeingDeleted，“指定的源路径标记为要删除”。 409 Conflict，ResourceTypeMismatch，“请求中指定的资源类型与资源类型不匹配。” 412 前置条件失败，ConditionNotMet，“未满足使用 HTTP 条件标头 () 指定的条件。” 412 前置条件失败，LeaseIdMismatch，“指定的租约 ID 与资源的租约 ID 不匹配。” 412 前置条件失败，LeaseIdMissing，“当前资源上有租约，请求中未指定租约 ID。” 412 前置条件失败，LeaseNotPresent，“资源当前没有租约。” 412 前置条件失败，LeaseLost，“已指定租约 ID，但资源的租约已过期。” 412 前置条件失败，SourceConditionNotMet，“未满足使用 HTTP 条件标头 () 指定的源条件。” 413 请求实体太大，RequestBodyTooLarge，“请求正文太大，超出允许的最大限制。” 416 请求的范围不可满足，InvalidRange，“指定的范围对于资源的当前大小无效。” 500 内部服务器错误，InternalError，“服务器遇到内部错误。 请重试请求。” 500 内部服务器错误 OperationTimedOut，“操作无法在允许的时间内完成。” 503 服务不可用，ServerBusy，“出口超出帐户限制。” 503 服务不可用，ServerBusy，“入口超出帐户限制。” 503 服务不可用，ServerBusy，“每秒操作数超过帐户限制。” 503 服务不可用，ServerBusy，“服务器当前无法接收请求。 请重试请求。” Headers x-ms-request-id: string x-ms-version: string

定义

名称	说明
AclFailedEntryList
DataLakeStorageError
Error	服务错误响应对象。
PathLeaseAction	从版本 2020-08-04 开始执行追加和刷新操作。 Append 支持“获取”、“自动续订”和“acquire-release”操作。 如果“获取”，它将获取租约。 如果“自动续订”，它将续订租约。 如果“acquire-release”，它将获取 & 完成操作 & 在操作完成后释放租约。 “释放”操作仅在刷新操作中受支持。 如果为“true”，将使用 x-ms-lease-id 标头中的租约 ID 信息释放文件上的租约。
PathUpdateAction	操作必须“追加”才能上传要追加到文件的数据，“刷新”将以前上传的数据刷新到文件，“setProperties”用于设置文件或目录的属性，“setAccessControl”用于设置文件或目录的所有者、组、权限或访问控制列表，或“setAccessControlRecursive”以递归方式设置目录的访问控制列表。 请注意，必须为帐户启用分层命名空间才能使用访问控制。 另请注意，访问控制列表 (ACL) 包括所有者、拥有组和其他人员的权限，因此 x-ms-permissions 和 x-ms-acl 请求标头互斥。
SetAccessControlRecursiveResponse

AclFailedEntryList

名称	类型	说明
errorMessage	string
name	string
type	string

DataLakeStorageError

名称	类型	说明
error	Error	服务错误响应对象。

Error

服务错误响应对象。

名称	类型	说明
code	string	服务错误代码。
message	string	服务错误消息。

PathLeaseAction

从版本 2020-08-04 开始执行追加和刷新操作。 Append 支持“获取”、“自动续订”和“acquire-release”操作。 如果“获取”，它将获取租约。 如果“自动续订”，它将续订租约。 如果“acquire-release”，它将获取 & 完成操作 & 在操作完成后释放租约。 “释放”操作仅在刷新操作中受支持。 如果为“true”，将使用 x-ms-lease-id 标头中的租约 ID 信息释放文件上的租约。

名称	类型	说明
acquire	string
acquire-release	string
auto-renew	string
release	string

PathUpdateAction

操作必须“追加”才能上传要追加到文件的数据，“刷新”将以前上传的数据刷新到文件，“setProperties”用于设置文件或目录的属性，“setAccessControl”用于设置文件或目录的所有者、组、权限或访问控制列表，或“setAccessControlRecursive”以递归方式设置目录的访问控制列表。 请注意，必须为帐户启用分层命名空间才能使用访问控制。 另请注意，访问控制列表 (ACL) 包括所有者、拥有组和其他人员的权限，因此 x-ms-permissions 和 x-ms-acl 请求标头互斥。

名称	类型	说明
append	string
flush	string
setAccessControl	string
setAccessControlRecursive	string
setProperties	string

SetAccessControlRecursiveResponse

名称	类型	说明
directoriesSuccessful	integer
failedEntries	AclFailedEntryList[]
failureCount	integer
filesSuccessful	integer