你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Path - Create
创建文件 |创建目录 |重命名文件 |重命名目录
创建或重命名文件或目录。 默认情况下,将覆盖目标,如果目标已存在并且具有租约,则租约中断。 请注意,除非源容器还具有匹配的强制容器加密策略,否则不允许将文件或目录重命名为容器。 此操作支持条件 HTTP 请求。 有关详细信息,请参阅 为 Blob 服务操作指定条件标头。 若要在目标已存在时失败,请使用具有 If-None-Match 的条件请求:“*”。
PUT https://{accountName}.{dnsSuffix}/{filesystem}/{path}
PUT https://{accountName}.{dnsSuffix}/{filesystem}/{path}?resource={resource}&continuation={continuation}&mode={mode}&timeout={timeout}
URI 参数
名称 | 在 | 必需 | 类型 | 说明 |
---|---|---|---|---|
account
|
path | True |
string |
Azure 存储帐户名称。 |
dns
|
path | True |
string |
Azure Data Lake Storage 终结点的 DNS 后缀。 |
filesystem
|
path | True |
string |
文件系统标识符。 正则表达式模式: |
path
|
path | True |
string |
文件或目录路径。 |
continuation
|
query |
string |
自选。 重命名目录时,使用每个调用重命名的路径数受到限制。 如果要重命名的路径数超过此限制,则会在此响应标头中返回延续标记。 在响应中返回继续标记时,必须在后续调用重命名操作中指定该标记才能继续重命名目录。 |
|
mode
|
query |
自选。 仅在启用命名空间时才有效。 此参数确定重命名操作的行为。 该值必须为“legacy”或“posix”,默认值为“posix”。 |
||
resource
|
query |
仅适用于创建文件和创建目录。 该值必须为“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 |
自选。 该服务存储此值并将其包含在“读取文件”操作的“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 必须匹配。 正则表达式模式: |
|
x-ms-source-lease-id |
string |
重命名操作可选。 源路径的租约 ID。 源路径必须具有活动租约,并且租约 ID 必须匹配。 正则表达式模式: |
|
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 位八进制表示法中,它由第一位数字表示(例如 1766 表示具有粘性位的 rwxrw-rw),0766 表示 rwxrw-rw-without粘性位)。 与 x-ms-acl 结合使用无效。 |
|
x-ms-umask |
string |
可选且仅在为帐户启用分层命名空间时才有效。 创建文件或目录时,父文件夹没有默认 ACL,umask 将限制要创建的文件或目录的权限。 生成的权限由 p & ^u 提供,其中 p 是权限,你是 umask。 例如,如果 p 为 0777 且为 0057,则生成的权限为 0720。 目录的默认权限为 0777,文件的默认权限为 0666。 默认的 umask 为 0027。 必须在 4 位八进制表示法(例如 0766)中指定 umask。 |
|
x-ms-owner |
string |
可选且仅在为帐户启用分层命名空间时才有效。 设置文件或目录的所有者。 |
|
x-ms-group |
string |
可选且仅在为帐户启用分层命名空间时才有效。 设置文件或目录的拥有组。 |
|
x-ms-acl |
string |
可选且仅在为帐户启用分层命名空间时才有效。 设置文件和目录的 POSIX 访问控制权限。 每个访问控制项(ACE)由范围、类型、用户或组标识符以及格式为“[scope:][type]:[id]:[permissions]”格式的权限组成。 范围必须为“default”,以指示 ACE 属于目录的默认 ACL;否则范围为隐式范围,ACE 属于访问 ACL。 有四种 ACE 类型:“user”向所有者或命名用户授予权限,“组”向拥有组或命名组授予权限,“掩码”将授予给命名用户和组成员的权限,“其他”向未在任何其他条目中找到的所有用户授予权限。 对于类型为“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 获取租约。 正则表达式模式: |
|
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-transaction-id |
string |
自选。 默认值为“Empty”。 如果设置该值,则会在文件创建或重命名时设置 Blob 元数据。 如果客户端的请求超时,则可以使用“获取属性”调用提取此值,以确认超时请求是否已在服务结束时成功或未成功。 最大长度 - 36。 仅在为帐户启用分层命名空间时有效。 |
|
x-ms-client-request-id |
string |
分析日志中记录的 UUID,用于故障排除和关联。 正则表达式模式: |
|
x-ms-date |
string |
指定请求的协调世界时(UTC)。 使用共享密钥授权时,这是必需的。 |
|
x-ms-version |
string |
指定用于处理请求的 REST 协议的版本。 使用共享密钥授权时,这是必需的。 |
响应
名称 | 类型 | 说明 |
---|---|---|
201 Created |
文件或目录已创建。 标头
|
|
Other Status Codes |
发生错误。 下面列出了可能的 HTTP 状态、代码和消息字符串:
标头
|
定义
名称 | 说明 |
---|---|
Data |
|
Error |
服务错误响应对象。 |
Path |
自选。 仅在启用命名空间时才有效。 此参数确定重命名操作的行为。 该值必须为“legacy”或“posix”,默认值为“posix”。 |
Path |
仅适用于创建文件和创建目录。 该值必须为“file”或“directory”。 |
DataLakeStorageError
名称 | 类型 | 说明 |
---|---|---|
error |
服务错误响应对象。 |
Error
服务错误响应对象。
名称 | 类型 | 说明 |
---|---|---|
code |
string |
服务错误代码。 |
message |
string |
服务错误消息。 |
PathRenameMode
自选。 仅在启用命名空间时才有效。 此参数确定重命名操作的行为。 该值必须为“legacy”或“posix”,默认值为“posix”。
名称 | 类型 | 说明 |
---|---|---|
legacy |
string |
|
posix |
string |
PathResourceType
仅适用于创建文件和创建目录。 该值必须为“file”或“directory”。
名称 | 类型 | 说明 |
---|---|---|
directory |
string |
|
file |
string |