azure.storage.filedatalake.DataLakeFileClient class

请求新的租约。如果文件或目录没有活动租约，DataLake 服务将在文件/目录上创建租约，并返回新的租约 ID。

acquire_lease(lease_duration: int | None = -1, lease_id: str | None = None, **kwargs) -> DataLakeLeaseClient

参数

lease_duration: int

必需

指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。有限期租约在 15 到 60 秒之间。不能使用续订或更改来更改租约持续时间。默认值为 -1， (无限租约) 。

lease_id: str

必需

建议的租约 ID，采用 GUID 字符串格式。如果建议的租约 ID 格式不正确，DataLake 服务将返回 400 (无效请求) 。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

可在上下文管理器中运行的 DataLakeLeaseClient 对象。

返回类型

DataLakeLeaseClient

将数据追加到文件。

append_data(data: bytes | str | Iterable[AnyStr] | IO[AnyStr], offset: int, length: int | None = None, **kwargs) -> Dict[str, str | datetime | int]

参数

data

必需

要追加到文件的内容

offset

必需

要追加到的数据的起始位置。

length

必需

数据的大小（以字节为单位）。

flush: bool

如果为 true，则会在追加数据后提交数据。

validate_content: bool

如果为 true，则计算块内容的 MD5 哈希。存储服务会检查随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https 作为 https， (默认) 已验证，则这主要用于检测网络上的 bitflips。请注意，此 MD5 哈希不随文件一起存储。

lease_action: Literal["acquire", "auto-renew", "release", "acquire-release"]

用于执行租用操作以及追加数据。

“acquire” - 获取租约。 “自动续订”- 重新创建现有租约。 “release” - 操作完成后释放租约。需要 flush=True。 “acquire-release”- 获取租约并在操作完成后释放它。需要 flush=True。

lease_duration: int

如果 lease_action 设置为“acquire”或“acquire-release”，则有效。

指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。有限期租约在 15 到 60 秒之间。不能使用续订或更改来更改租约持续时间。默认值为 -1， (无限租约) 。

lease: DataLakeLeaseClient 或 str

如果文件具有活动租约，或者 lease_action 设置为“acquire”或“acquire-release”，则是必需的。如果文件具有现有的租约，则它将用于访问该文件。如果获取新的租约，则它将用作新的租约 ID。值可以是 DataLakeLeaseClient 对象，也可以是作为字符串的租用 ID。

cpk: CustomerProvidedEncryptionKey

使用给定的密钥加密服务端上的数据。必须使用 HTTPS 使用客户提供的密钥。

返回

响应标头的 dict

示例

将数据追加到文件。


   file_client.append_data(data=file_content[2048:3072], offset=2048, length=1024)

此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。

close() -> None

创建新的文件。

create_file(content_settings: ContentSettings | None = None, metadata: Dict[str, str] | None = None, **kwargs) -> Dict[str, str | datetime]

参数

content_settings: ContentSettings

必需

用于设置路径属性的 ContentSettings 对象。

metadata: Optional[Dict[str, str]]

必需

作为元数据、与文件关联的名称-值对。

lease: DataLakeLeaseClient 或 str

如果文件具有活动租约，则为必需。值可以是 DataLakeLeaseClient 对象，也可以是作为字符串的租用 ID。

umask: str

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

owner: str

文件或目录的所有者。

group: str

文件或目录的拥有组。

acl: str

设置对文件和目录的 POSIX 访问控制权限。该值是访问控制项的逗号分隔列表。每个访问控制项 (ACE) 由范围、类型、用户或组标识符以及格式为“[scope：][type]：[id]：[permissions]”的权限组成。

lease_id: str

建议的租约 ID，采用 GUID 字符串格式。如果建议的租约 ID 格式不正确，DataLake 服务将返回 400 (无效请求) 。

lease_duration: int

指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。有限期租约在 15 到 60 秒之间。不能使用续订或更改来更改租约持续时间。

expires_on: datetime 或 int

将文件设置为过期的时间。如果expires_on的类型为 int，则过期时间将设置为从创建时间开始经过的毫秒数。如果expires_on的类型为 datetime，则过期时间将绝对设置为提供的时间。如果未提供时区信息，则会将其解释为 UTC。

permissions: str

可选，并且仅在为帐户启用分层命名空间时有效。为文件所有者、文件拥有组等设置 POSIX 访问权限。可以向每个类授予读取、写入或执行权限。还支持粘滞位。支持符号 (rwxrw-rw-) 和 4 位八进制表示法 (，例如 0766) 。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

cpk: CustomerProvidedEncryptionKey

使用给定的密钥加密服务端上的数据。必须使用 HTTPS 使用客户提供的密钥。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

encryption_context: str

指定要对文件设置的加密上下文。

返回

响应 dict (Etag 和上次修改) 。

示例

创建文件。


   file_client = filesystem_client.get_file_client(file_name)
   file_client.create_file()

标记要删除的指定文件。

delete_file(**kwargs) -> None

参数

lease: DataLakeLeaseClient 或 str

如果文件具有活动租约，则为必需。值可以是 LeaseClient 对象，也可以是作为字符串的租用 ID。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

无

示例

删除文件。


   new_client.delete_file()

将文件下载到 StorageStreamDownloader。必须使用 readall () 方法读取所有内容，或使用 readinto () 将文件下载到流中。使用 chunks () 将返回一个迭代器，该迭代器允许用户循环访问区块中的内容。

download_file(offset: int | None = None, length: int | None = None, **kwargs: Any) -> StorageStreamDownloader

参数

offset: int

必需

要用于下载文件的某个部分的字节范围的起始。如果提供了长度，则必须设置。

length: int

必需

要从流中读取的字节数。这是可选的，但应提供以获得最佳性能。

lease: DataLakeLeaseClient 或 str

如果指定，则仅当文件的租约处于活动状态且与此 ID 匹配时，下载才会成功。如果文件具有活动租约，则为必需。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

cpk: CustomerProvidedEncryptionKey

使用给定密钥解密服务端上的数据。必须使用 HTTPS 使用客户提供的密钥。如果文件是使用 Customer-Provided 密钥创建的，则为必需项。

max_concurrency: int

要下载的并行连接数。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。此方法可能会对服务进行多次调用，超时将分别应用于每个调用。

返回

(StorageStreamDownloader) 的流式处理对象

返回类型

StorageStreamDownloader

示例

返回下载的数据。


   download = file_client.download_file()
   downloaded_bytes = download.readall()

如果文件存在，则返回 True，否则返回 False。

exists(**kwargs: Any) -> bool

参数

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

如果存在文件，则为 True，否则返回 False。

返回类型

bool

提交上一个追加的数据。

flush_data(offset: int, retain_uncommitted_data: bool | None = False, **kwargs) -> Dict[str, str | datetime]

参数

offset

必需

offset 等于提交上一个追加数据后的文件长度。

retain_uncommitted_data: bool

必需

仅对刷新操作有效。如果为“true”，则刷新操作完成后保留未提交的数据;否则，刷新操作后会删除未提交的数据。默认值为 false。刷新成功时，偏移量小于指定位置的数据将写入文件，但此可选参数允许保留刷新位置后的数据以供将来的刷新操作使用。

content_settings: ContentSettings

用于设置路径属性的 ContentSettings 对象。

close: bool

Azure 存储事件允许应用程序在文件更改时接收通知。启用 Azure 存储事件后，将引发文件更改事件。此事件具有一个属性，指示这是否是最终更改，以区分文件流的中间刷新与文件流最终关闭之间的差异。仅当操作为“刷新”并启用更改通知时，close 查询参数才有效。如果 close 的值为“true”并且刷新操作成功完成，则服务会引发文件更改通知，其中包含一个属性，指示这是 (文件流) 关闭的最终更新。如果“false”，则会引发更改通知，指示文件已更改。默认值为 false。 Hadoop ABFS 驱动程序将此查询参数设置为 true，以指示文件流已关闭。”

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

在 etag 上使用的匹配条件。

lease_action: Literal["acquire", "auto-renew", "release", "acquire-release"]

用于执行租约操作以及追加数据。

“获取”- 获取租约。 “自动续订”- 重新创建现有租约。 “release” - 在操作完成后释放租约。 “acquire-release”- 获取租约并在操作完成后释放它。

lease_duration: int

如果 lease_action 设置为“acquire”或“acquire-release”，则有效。

指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。有限期租约在 15 到 60 秒之间。不能使用续订或更改来更改租约持续时间。默认值为 -1 (无限租用) 。

lease: DataLakeLeaseClient 或 str

如果文件具有活动租约，或者 lease_action 设置为“acquire”或“acquire-release”，则是必需的。如果文件具有现有租约，则它将用于访问该文件。如果获取新租约，则会将其用作新租约 ID。值可以是 DataLakeLeaseClient 对象，也可以是租约 ID 作为字符串。

cpk: CustomerProvidedEncryptionKey

使用给定密钥加密服务端的数据。客户提供的密钥的使用必须通过 HTTPS 完成。

返回

dict 中的响应标头

示例

提交上一个追加的数据。


   with open(SOURCE_FILE, "rb") as data:
       file_client = file_system_client.get_file_client("myfile")
       file_client.create_file()
       file_client.append_data(data, 0)
       file_client.flush_data(data.tell())

从连接字符串创建 DataLakeFileClient。

：return a DataLakeFileClient ：rtype ~azure.storage.filedatalake.DataLakeFileClient

from_connection_string(conn_str: str, file_system_name: str, file_path: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

参数

conn_str: str

必需

Azure 存储帐户的连接字符串。

file_system_name: str

必需

要与之交互的文件系统的名称。

file_path: str

必需

整个文件路径，以便与特定文件交互。例如 “{directory}/{subdirectory}/{file}”

credential

默认值: None

用于进行身份验证的凭据。如果帐户 URL 已具有 SAS 令牌，或者连接字符串已具有共享访问密钥值，则这是可选的。该值可以是 SAS 令牌字符串、azure.core.credentials 中的 AzureSasCredential 或 AzureNamedKeyCredential 的实例、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。此处提供的凭据优先于连接字符串中的凭据。如果使用 AzureNamedKeyCredential 的实例，“name”应为存储帐户名称，“key”应为存储帐户密钥。

get_access_control(upn: bool | None = None, **kwargs) -> Dict[str, Any]

参数

upn: bool

必需

可选。仅当为帐户启用分层命名空间时有效。如果为“true”，则 x-ms-owner、x-ms-group 和 x-ms-acl 响应标头中返回的用户标识值将从 Azure Active Directory 对象 ID 转换为用户主体名称。如果为“false”，则值将作为 Azure Active Directory 对象 ID 返回。默认值为 false。请注意，不会转换组和应用程序对象 ID，因为它们没有唯一的友好名称。

lease: DataLakeLeaseClient 或 str

如果文件/目录具有活动租约，则是必需的。值可以是 LeaseClient 对象，也可以是租约 ID 作为字符串。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

在 etag 上使用的匹配条件。

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

response dict

响应 dict。

返回文件的所有用户定义的元数据、标准 HTTP 属性和系统属性。它不返回文件的内容。

get_file_properties(**kwargs: Any) -> FileProperties

参数

lease

如果目录或文件具有活动租约，则是必需的。值可以是 DataLakeLeaseClient 对象，也可以是租约 ID 作为字符串。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

在 etag 上使用的匹配条件。

cpk: CustomerProvidedEncryptionKey

使用给定密钥解密服务端的数据。客户提供的密钥的使用必须通过 HTTPS 完成。如果文件是使用客户提供的密钥创建的，则是必需的。

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

文件的所有用户定义的元数据、标准 HTTP 属性和系统属性。

返回类型

FileProperties

示例

获取文件的属性。


   properties = file_client.get_file_properties()

允许用户通过提供简单的查询表达式来选择/投影 datalake 文件数据。此操作返回 DataLakeFileQueryReader，用户需要使用 readall () 或 readinto () 获取查询数据。

query_file(query_expression: str, **kwargs: Any) -> DataLakeFileQueryReader

参数

query_expression: str

必需

必需。查询语句。例如从 DataLakeStorage 中选择 *

on_error: Callable[DataLakeFileQueryError]

要针对服务返回的任何处理错误调用的函数。

file_format: DelimitedTextDialect 或 DelimitedJsonDialect 或 QuickQueryDialect 或 str

可选。定义当前存储在文件中的数据的序列化。默认设置是将文件数据视为采用默认方言格式的 CSV 数据。这可以通过自定义 DelimitedTextDialect、DelimitedJsonDialect 或“ParquetDialect” (作为字符串或枚举) 传递来重写。这些方言可以通过各自的类（QuickQueryDialect 枚举或字符串）传递。

output_format: DelimitedTextDialect 或 DelimitedJsonDialect 或 list[ArrowDialect] 或 QuickQueryDialect 或 str

可选。定义数据流的输出序列化。默认情况下，将返回数据，因为它在文件中表示。通过提供输出格式，将根据该配置文件重新格式化文件数据。此值可以是 DelimitedTextDialect 或 DelimitedJsonDialect 或 ArrowDialect。这些方言可以通过各自的类（QuickQueryDialect 枚举或字符串）传递。

lease: DataLakeLeaseClient 或 str

如果文件具有活动租约，则为必需。值可以是 DataLakeLeaseClient 对象，也可以是租约 ID 作为字符串。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

在 etag 上使用的匹配条件。

cpk: CustomerProvidedEncryptionKey

使用给定密钥解密服务端的数据。客户提供的密钥的使用必须通过 HTTPS 完成。如果文件是使用 Customer-Provided 密钥创建的，则是必需的。

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

DataLakeFileQueryReader (流式处理对象)

返回类型

<xref:azure.storage.filedatalake.DataLakeFileQueryReader>

示例

通过提供简单的查询表达式，选择/投影 datalake 文件数据。


   errors = []
   def on_error(error):
       errors.append(error)

   # upload the csv file
   file_client = datalake_service_client.get_file_client(filesystem_name, "csvfile")
   file_client.upload_data(CSV_DATA, overwrite=True)

   # select the second column of the csv file
   query_expression = "SELECT _2 from DataLakeStorage"
   input_format = DelimitedTextDialect(delimiter=',', quotechar='"', lineterminator='\n', escapechar="", has_header=False)
   output_format = DelimitedJsonDialect(delimiter='\n')
   reader = file_client.query_file(query_expression, on_error=on_error, file_format=input_format, output_format=output_format)
   content = reader.readall()

删除路径和子路径上的访问控制。

remove_access_control_recursive(acl: str, **kwargs: Any) -> AccessControlChangeResult

参数

acl: str

必需

删除对文件和目录的 POSIX 访问控制权限。该值是一个以逗号分隔的访问控制项列表。 ACE) (每个访问控制项都由一个范围、一个类型和一个用户或组标识符组成，格式为“[scope：][type]：[id]”。

progress_hook: <xref:func>(AccessControlChanges)

调用方可以跟踪操作进度以及收集无法更改访问控制的路径的回调。

continuation_token: str

可用于恢复以前停止的操作的可选继续标记。

batch_size: int

可选。如果数据集大小超过批大小，则操作将拆分为多个请求，以便可以跟踪进度。批大小应介于 1 到 2000 之间。未指定时的默认值为 2000。

max_batches: int

可选。定义单个更改访问控制操作可以执行的最大批数。如果在处理所有子路径之前达到最大值，则可以使用继续标记继续操作。空值指示未绑定的最大批数，并且操作一直持续到结束。

continue_on_failure: bool

如果设置为 False，则操作将在遇到用户错误 (4XX) 快速终止。如果为 True，则操作将忽略用户错误，并继续对目录的其他子实体执行该操作。仅当continue_on_failure为 True 时，才会返回用户错误时的延续标记。如果未设置，则默认值为 False。

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

递归操作的摘要，包括成功和失败的计数，以及在操作过早终止的情况下的继续标记。

返回类型

AccessControlChangeResult

例外

AzureError

如果令牌可用，用户可以使用 AzureError 的continuation_token字段重启操作。

重命名源文件。

rename_file(new_name: str, **kwargs: Any) -> DataLakeFileClient

参数

new_name: str

必需

用户要重命名为的新文件名。该值必须具有以下格式：“{filesystem}/{directory}/{subdirectory}/{file}”。

content_settings: ContentSettings

用于设置路径属性的 ContentSettings 对象。

source_lease: DataLakeLeaseClient 或 str

源路径的租约 ID。如果指定，则源路径必须具有活动租约，并且租约 ID 必须匹配。

lease

如果文件/目录具有活动租约，则是必需的。值可以是 LeaseClient 对象，也可以是租约 ID 作为字符串。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

在 etag 上使用的匹配条件。

source_if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

source_if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

source_etag: str

源 ETag 值或通配符 (*) 。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

source_match_condition: MatchConditions

要用于 etag 的源匹配条件。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

重命名的文件客户端

返回类型

DataLakeFileClient

示例

重命名源文件。


   new_client = file_client.rename_file(file_client.file_system_name + '/' + 'newname')

设置路径的所有者、组、权限或访问控制列表。

set_access_control(owner: str | None = None, group: str | None = None, permissions: str | None = None, acl: str | None = None, **kwargs) -> Dict[str, str | datetime]

参数

owner: str

必需

可选。文件或目录的所有者。

group: str

必需

可选。文件或目录的拥有组。

permissions: str

必需

可选，并且仅在为帐户启用分层命名空间时有效。为文件所有者、文件拥有组等设置 POSIX 访问权限。可以向每个类授予读取、写入或执行权限。还支持粘滞位。支持符号 (rwxrw-rw-) 和 4 位八进制表示法 (，例如 0766) 。权限和 acl 是互斥的。

acl: str

必需

设置对文件和目录的 POSIX 访问控制权限。该值是访问控制项的逗号分隔列表。每个访问控制项 (ACE) 由范围、类型、用户或组标识符以及格式为“[scope：][type]：[id]：[permissions]”的权限组成。权限和 acl 是互斥的。

lease: DataLakeLeaseClient 或 str

如果文件/目录具有活动租约，则为必需。值可以是 LeaseClient 对象，也可以是作为字符串的租用 ID。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

response dict

响应 dict (Etag 和上次修改) 。

设置路径和子路径上的访问控制。

set_access_control_recursive(acl: str, **kwargs: Any) -> AccessControlChangeResult

参数

acl: str

必需

设置对文件和目录的 POSIX 访问控制权限。该值是访问控制项的逗号分隔列表。每个访问控制项 (ACE) 由范围、类型、用户或组标识符以及格式为“[scope：][type]：[id]：[permissions]”的权限组成。

progress_hook: <xref:func>(AccessControlChanges)

调用方可以跟踪操作进度以及收集无法更改访问控制的路径的回调。

continuation_token: str

可用于恢复以前停止的操作的可选继续标记。

batch_size: int

可选。如果数据集大小超过批大小，则操作将拆分为多个请求，以便跟踪进度。批大小应介于 1 和 2000 之间。未指定时的默认值为 2000。

max_batches: int

可选。定义单个更改访问控制操作可以执行的最大批数。如果在处理所有子路径之前达到最大值，则可以使用继续标记继续操作。空值指示未绑定的最大批数和操作一直持续到结束。

continue_on_failure: bool

如果设置为 False，则遇到用户错误 (4XX) 时，操作将快速终止。如果为 True，则操作将忽略用户错误，并继续对目录的其他子实体执行该操作。仅当用户出错时，continue_on_failure为 True 时，才会返回延续令牌。如果未设置，则默认值为 False。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

递归操作的摘要，包括成功和失败的计数，以及在操作过早终止的情况下的继续标记。

返回类型

AccessControlChangeResult

例外

AzureError

如果令牌可用，用户可以使用 AzureError 的continuation_token字段重启操作。

设置文件过期和删除的时间。

set_file_expiry(expiry_options: str, expires_on: datetime | int | None = None, **kwargs) -> None

参数

expiry_options: str

必需

必需。指示到期时间的模式。可能的值包括：“NeverExpire”、“RelativeToCreation”、“RelativeToNow”、“Absolute”

expires_on: datetime 或 int

必需

将文件设置为过期的时间。当expiry_options为 RelativeTo*时，expires_on应为 int（以毫秒为单位）。如果expires_on的类型为 datetime，则它应采用 UTC 时间。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回类型

None

设置文件或目录上的系统属性。

如果为content_settings设置了一个属性，则将重写所有属性。

set_http_headers(content_settings: ContentSettings | None = None, **kwargs) -> Dict[str, Any]

参数

content_settings: ContentSettings

必需

用于设置文件/目录属性的 ContentSettings 对象。

lease: DataLakeLeaseClient 或 str

如果指定，则仅当文件系统的租约处于活动状态并且与此 ID 匹配时，set_file_system_metadata才会成功。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

文件/目录更新的属性 dict (Etag 和上次修改)

返回类型

Dict[str, Any]

为指定的文件系统设置一个或多个用户定义的名称/值对。每次调用此操作都会替换附加到文件系统的所有现有元数据。若要从文件系统中删除所有元数据，请调用此操作，不带元数据 dict。

set_metadata(metadata: Dict[str, str], **kwargs) -> Dict[str, str | datetime]

参数

metadata: Dict[str, str]

必需

包含要作为元数据与文件系统关联的名称/值对的 dict。示例：{'category'：'test'}

lease: DataLakeLeaseClient 或 str

如果指定，则仅当文件系统的租约处于活动状态并且与此 ID 匹配时，set_file_system_metadata才会成功。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

cpk: CustomerProvidedEncryptionKey

使用给定的密钥加密服务端上的数据。必须使用 HTTPS 使用客户提供的密钥。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

文件系统更新的属性 dict (Etag 和上次修改) 。

修改路径和子路径上的访问控制。

update_access_control_recursive(acl: str, **kwargs: Any) -> AccessControlChangeResult

参数

acl: str

必需

修改对文件和目录的 POSIX 访问控制权限。该值是访问控制项的逗号分隔列表。每个访问控制项 (ACE) 由范围、类型、用户或组标识符以及格式为“[scope：][type]：[id]：[permissions]”的权限组成。

progress_hook: <xref:func>(AccessControlChanges)

调用方可以跟踪操作进度以及收集无法更改访问控制的路径的回调。

continuation_token: str

可用于恢复以前停止的操作的可选继续标记。

batch_size: int

可选。如果数据集大小超过批大小，则操作将拆分为多个请求，以便跟踪进度。批大小应介于 1 和 2000 之间。未指定时的默认值为 2000。

max_batches: int

可选。定义单个更改访问控制操作可以执行的最大批数。如果在处理所有子路径之前达到最大值，则可以使用继续标记继续操作。空值指示未绑定的最大批数和操作一直持续到结束。

continue_on_failure: bool

如果设置为 False，则遇到用户错误 (4XX) 时，操作将快速终止。如果为 True，则操作将忽略用户错误，并继续对目录的其他子实体执行该操作。仅当用户出错时，continue_on_failure为 True 时，才会返回延续令牌。如果未设置，则默认值为 False。

timeout: int

设置操作的服务器端超时时间（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

递归操作的摘要，包括成功和失败的计数，以及在操作过早终止的情况下的继续标记。

返回类型

AccessControlChangeResult

例外

AzureError

如果令牌可用，用户可以使用 AzureError 的continuation_token字段重启操作。

将数据上传到文件。

upload_data(data: bytes | str | Iterable | IO, length: int | None = None, overwrite: bool | None = False, **kwargs) -> Dict[str, Any]

参数

data

必需

要上传到文件的内容

length: int

必需

数据的大小（以字节为单位）。

overwrite: bool

必需

是否覆盖现有文件。

content_settings: ContentSettings

用于设置路径属性的 ContentSettings 对象。

metadata: Optional[Dict[str, str]]

作为元数据、与 Blob 关联的名称-值对。

lease: DataLakeLeaseClient 或 str

如果 Blob 具有活动租约，则是必需的。值可以是 DataLakeLeaseClient 对象，也可以是作为字符串的租用 ID。

umask: str

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

permissions: str

可选，并且仅在为帐户启用分层命名空间时有效。为文件所有者、文件拥有组等设置 POSIX 访问权限。可以向每个类授予读取、写入或执行权限。还支持粘滞位。支持符号 (rwxrw-rw-) 和 4 位八进制表示法 (，例如 0766) 。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

validate_content: bool

如果为 true，则计算文件的每个区块的 MD5 哈希。存储服务会检查随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https，这主要用于检测网络上的 bitflips，因为默认) (https 已经进行了验证。请注意，此 MD5 哈希值不与 Blob 一起存储。另请注意，如果启用，将不会使用内存高效上传算法，因为计算 MD5 哈希需要缓冲整个块，这样做会破坏内存高效算法的用途。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

match_condition: MatchConditions

要对 etag 使用的匹配条件。

cpk: CustomerProvidedEncryptionKey

使用给定的密钥加密服务端上的数据。必须使用 HTTPS 使用客户提供的密钥。

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。此方法可能会对服务进行多次调用，超时将单独应用于每个调用。

chunk_size: int

用于在区块中上传文件的最大区块大小。默认为 100*1024*1024 或 100MB。

encryption_context: str

指定要在文件上设置的加密上下文。

返回

响应 dict (Etag 和上次修改) 。

用于请求的存储 API 的版本。

客户端当前使用的位置模式。

默认情况下，此为“主要”。选项包括“primary”和“secondary”。

完整的主终结点 URL。

主终结点的主机名。

完整的辅助终结点 URL（如果已配置）。

如果不可用，将引发 ValueError。若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

例外

ValueError

辅助终结点的主机名。

如果不可用，则此项将为“无”。若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。

这可以是主终结点，也可以是辅助终结点，具体取决于当前 location_mode。：returns：此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。 :rtype：str

acquire_lease	请求新的租约。如果文件或目录没有活动租约，DataLake 服务将在文件/目录上创建租约，并返回新的租约 ID。
append_data	将数据追加到文件。
close	此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。
create_file	创建新的文件。
delete_file	标记要删除的指定文件。
download_file	将文件下载到 StorageStreamDownloader。必须使用 readall () 方法读取所有内容，或使用 readinto () 将文件下载到流中。使用 chunks () 将返回一个迭代器，该迭代器允许用户循环访问区块中的内容。
exists	如果文件存在，则返回 True，否则返回 False。
flush_data	提交上一个追加的数据。
from_connection_string	从连接字符串创建 DataLakeFileClient。：return a DataLakeFileClient ：rtype ~azure.storage.filedatalake.DataLakeFileClient
get_access_control
get_file_properties	返回文件的所有用户定义的元数据、标准 HTTP 属性和系统属性。它不返回文件的内容。
query_file	允许用户通过提供简单的查询表达式来选择/投影 datalake 文件数据。此操作返回 DataLakeFileQueryReader，用户需要使用 readall () 或 readinto () 获取查询数据。
remove_access_control_recursive	删除路径和子路径上的访问控制。
rename_file	重命名源文件。
set_access_control	设置路径的所有者、组、权限或访问控制列表。
set_access_control_recursive	设置路径和子路径上的访问控制。
set_file_expiry	设置文件过期和删除的时间。
set_http_headers	设置文件或目录上的系统属性。如果为content_settings设置了一个属性，则将重写所有属性。
set_metadata	为指定的文件系统设置一个或多个用户定义的名称/值对。每次调用此操作都会替换附加到文件系统的所有现有元数据。若要从文件系统中删除所有元数据，请调用此操作，不带元数据 dict。
update_access_control_recursive	修改路径和子路径上的访问控制。
upload_data	将数据上传到文件。

通过

DataLakeFileClient 类

构造函数

参数

示例

变量

方法

acquire_lease

参数

返回

返回类型

append_data

参数

返回

示例

close

create_file

参数

返回

示例

delete_file

参数

返回

示例

download_file

参数

返回

返回类型

示例

exists

参数

返回

返回类型

flush_data

参数

返回

示例

from_connection_string

参数

get_access_control

参数

get_file_properties

参数

返回

返回类型

示例

query_file

参数

返回

返回类型

示例

remove_access_control_recursive

参数

返回

返回类型

例外

rename_file

参数

返回

返回类型

示例

set_access_control

参数

set_access_control_recursive

参数

返回

返回类型

例外

set_file_expiry

参数

返回类型

set_http_headers

参数

返回

返回类型

set_metadata

参数

返回

update_access_control_recursive

参数