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

Path - Create

  • 参考
Service:
Storage Services
API Version:
2023-08-03

创建文件 |创建目录 |重命名文件 |重命名目录
创建或重命名文件或目录。 默认情况下，目标将被覆盖，如果目标已存在且具有租约，则租约中断。 请注意，不允许使用强制容器加密策略将文件或目录重命名为容器，除非源容器还具有匹配的强制容器加密策略。 此操作支持条件 HTTP 请求。 有关详细信息，请参阅为 Blob 服务操作指定条件标头。 若要在目标已存在的情况下失败，请使用条件请求和 If-None-Match：“*”。

PUT https://{accountName}.{dnsSuffix}/{filesystem}/{path}
With optional parameters: 
PUT https://{accountName}.{dnsSuffix}/{filesystem}/{path}?resource={resource}&continuation={continuation}&mode={mode}&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

文件或目录路径。
continuation
 query

string

可选。 重命名目录时，每次调用时重命名的路径数是有限的。 如果要重命名的路径数超过此限制，则会在此响应标头中返回延续标记。 在响应中返回延续标记时，必须在重命名操作的后续调用中指定它，才能继续重命名目录。
mode
 query

PathRenameMode

可选。 仅在启用命名空间时有效。 此参数确定重命名操作的行为。 该值必须为“legacy”或“posix”，默认值为“posix”。
resource
 query

PathResourceType

仅对“创建文件”和“创建目录”是必需的。 该值必须为“file”或“directory”。
timeout
 query

integer

int32

可选的操作超时值（以秒为单位）。 时间段从服务接收请求时开始。 如果超时值在操作完成之前已过，则操作将失败。

请求头

Media Types: "application/octet-stream"

名称 必需 类型 说明
Cache-Control

string

可选。 该服务存储此值，并将其包含在“Cache-Control”响应标头中，用于“读取文件”操作的“读取文件”操作。
Content-Encoding

string

可选。 指定对文件应用了哪种内容编码。 执行“读取文件”操作时，此值将返回到客户端。
Content-Language

string

可选。 指定目标受众对文件使用的自然语言。
Content-Disposition

string

可选。 该服务存储此值，并将其包含在“读取文件”操作的“Content-Disposition”响应标头中。
x-ms-cache-control

string

可选。 服务存储此值，并将其包含在“读取文件”操作的“Cache-Control”响应标头中。
x-ms-content-type

string

可选。 该服务存储此值，并将其包含在“读取文件”操作的“Content-Type”响应标头中。
x-ms-content-encoding

string

可选。 服务存储此值，并将其包含在“读取文件”操作的“Content-Encoding”响应标头中。
x-ms-content-language

string

可选。 该服务存储此值，并将其包含在“Read File”操作的“Content-Language”响应标头中。
x-ms-content-disposition

string

可选。 该服务存储此值，并将其包含在“读取文件”操作的“Content-Disposition”响应标头中。
x-ms-rename-source

string

要重命名的可选文件或目录。 使用 SAS 令牌时，该值必须具有以下格式：“/{filesystem}/{path}”或“/{filesystem}/{path}？sastoken”。 如果指定了“x-ms-properties”，则属性将覆盖现有属性;否则，将保留现有属性。 此值必须是 URL 百分比编码字符串。 请注意，字符串在 ISO-8859-1 字符集中只能包含 ASCII 字符。
x-ms-lease-id

string

可选。 URI 中指定的路径的租约 ID。 要覆盖的路径必须具有活动租约，并且租约 ID 必须匹配。

Regex pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-source-lease-id

string

重命名操作可选。 源路径的租约 ID。 源路径必须具有活动租约，并且租约 ID 必须匹配。

Regex pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-properties

string

可选。 要与文件或目录一起存储的用户定义的属性，格式为逗号分隔的名称和值对列表“n1=v1，n2=v2，...”，其中每个值都是 base64 编码字符串。 请注意，字符串在 ISO-8859-1 字符集中只能包含 ASCII 字符。
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-umask

string

可选，仅当为帐户启用分层命名空间时有效。 创建文件或目录且父文件夹没有默认 ACL 时，umask 会限制要创建的文件或目录的权限。 生成的权限由 p & ^u 授予，其中 p 是权限，而您是 umask。 例如，如果 p 为 0777，而您为 0057，则生成的权限为 0720。 目录的默认权限为 0777，文件的默认权限为 0666。 默认的 umask 为 0027。 必须使用 4 位八进制表示法 (指定 umask，例如 0766) 。
x-ms-owner

string

可选，仅当为帐户启用分层命名空间时有效。 设置文件或目录的所有者。
x-ms-group

string

可选，仅当为帐户启用分层命名空间时有效。 设置文件或目录的拥有组。
x-ms-acl

string

可选，仅当为帐户启用分层命名空间时有效。 设置对文件和目录的 POSIX 访问控制权限。 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 一起无效。
x-ms-proposed-lease-id

string

可选。 如果要在创建文件或目录期间获取租约，请指定建议的租约 ID。 如果创建成功，将使用此租约 ID 获取租约。

Regex pattern: ^[{(]?[0-9a-f]{8}[-]?([0-9a-f]{4}[-]?){3}[0-9a-f]{12}[)}]?$
x-ms-expiry-option

string

可选且仅当为帐户启用了分层命名空间且仅在文件上受支持时才有效。 如果要在创建文件时设置到期时间，请指定以下到期选项之一。 “RelativeToNow”设置相对于当前时间的到期时间。 用户将传递从现在开始经过的毫秒数。 RFC 1123 格式的“绝对”绝对时间。 “Neverexpire”将文件设置为永不过期，不需要使用此选项指定过期时间。
x-ms-expiry-time

string

可选且仅当为帐户启用了分层命名空间且仅在文件上受支持时才有效。 指定文件的过期时间。 根据到期选项，以 RFC 1123 HTTP 时间字符串或毫秒数的形式提供。
If-Match

string

可选。 ETag 值。 指定此标头，以便仅在资源的 ETag 与指定的值匹配时才执行操作。 必须在引号中指定 ETag。
If-None-Match

string

可选。 ETag 值或特殊通配符 (“*”) 值。 指定此标头，以便仅在资源的 ETag 与指定的值不匹配时才执行操作。 必须在引号中指定 ETag。
If-Modified-Since

string

可选。 日期和时间值。 指定此标头以仅当资源自指定日期和时间以来已修改时才执行操作。
If-Unmodified-Since

string

可选。 日期和时间值。 指定此标头以仅当资源自指定日期和时间以来未修改时才执行操作。
x-ms-source-if-match

string

可选。 ETag 值。 指定此标头以仅当源的 ETag 与指定的值匹配时执行重命名操作。 必须在引号中指定 ETag。
x-ms-source-if-none-match

string

可选。 ETag 值或特殊通配符 (“*”) 值。 指定此标头以仅当源的 ETag 与指定的值不匹配时执行重命名操作。 必须在引号中指定 ETag。
x-ms-source-if-modified-since

string

可选。 日期和时间值。 指定此标头以仅当源自指定日期和时间以来已修改时才执行重命名操作。
x-ms-source-if-unmodified-since

string

可选。 日期和时间值。 指定此标头以仅当源自指定日期和时间以来未修改时执行重命名操作。
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-encryption-context

string

可选。 默认值为“Empty”。 如果设置了该值，它将设置 Blob/文件系统元数据。 最大长度 - 1024。 仅当为帐户启用分层命名空间时有效。
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 协议的版本。 使用共享密钥授权时，这是必需的。

响应

名称 类型 说明
201 Created

文件或目录已创建。

Headers

  • Date: string
  • ETag: string
  • Last-Modified: string
  • x-ms-request-id: string
  • x-ms-version: string
  • x-ms-continuation: string
  • Content-Length: integer
  • x-ms-request-server-encrypted: true/false: boolean
  • x-ms-encryption-key-sha256: string
  • x-ms-encryption-scope: string
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

定义

名称 说明
DataLakeStorageError
Error

服务错误响应对象。
PathRenameMode

可选。 仅在启用命名空间时有效。 此参数确定重命名操作的行为。 该值必须为“legacy”或“posix”，默认值为“posix”。
PathResourceType

仅对“创建文件”和“创建目录”是必需的。 该值必须为“file”或“directory”。

DataLakeStorageError

名称 类型 说明
error

Error

服务错误响应对象。

Error

服务错误响应对象。

名称 类型 说明
code

string

服务错误代码。
message

string

服务错误消息。

PathRenameMode

可选。 仅在启用命名空间时有效。 此参数确定重命名操作的行为。 该值必须为“legacy”或“posix”，默认值为“posix”。

名称 类型 说明
legacy

string

posix

string

PathResourceType

仅对“创建文件”和“创建目录”是必需的。 该值必须为“file”或“directory”。

名称 类型 说明
directory

string

file

string