通过

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

DataLakeServiceClient 类

  • 参考

在帐户级别与 DataLake 服务交互的客户端。

此客户端提供检索和配置帐户属性以及列出、创建和删除帐户中的文件系统的操作。 对于与特定文件系统、目录或文件相关的操作，也可以使用 get_client 函数检索这些实体的客户端。

继承
azure.storage.filedatalake._shared.base_client.StorageAccountHostsMixin
DataLakeServiceClient

构造函数

DataLakeServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

参数

account_url
str
必需

DataLake 存储帐户的 URL。 URL 路径 (中包含的任何其他实体（例如文件系统或文件) ）将被丢弃。 可以选择使用 SAS 令牌对此 URL 进行身份验证。

credential
默认值: None

用于进行身份验证的凭据。 如果帐户 URL 已有 SAS 令牌，则这是可选的。 该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 如果资源 URI 已包含 SAS 令牌，则会忽略此令牌，转而使用显式凭据

  • AzureSasCredential 的情况除外，其中冲突的 SAS 令牌将引发 ValueError。 如果使用 AzureNamedKeyCredential 的实例，则“name”应为存储帐户名称，“密钥”应为存储帐户密钥。
api_version
str

用于请求的存储 API 版本。 默认值是与当前 SDK 兼容的最新服务版本。 设置为较旧版本可能会导致功能兼容性降低。

示例

从连接字符串创建 DataLakeServiceClient。


   from azure.storage.filedatalake import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

使用 Azure 标识凭据创建 DataLakeServiceClient。


   from azure.identity import ClientSecretCredential
   token_credential = ClientSecretCredential(
       self.active_directory_tenant_id,
       self.active_directory_application_id,
       self.active_directory_application_secret,
   )
   datalake_service_client = DataLakeServiceClient("https://{}.dfs.core.windows.net".format(self.account_name),
                                                   credential=token_credential)

变量

url
str

datalake 服务终结点的完整终结点 URL。

primary_endpoint
str

完整的主终结点 URL。

primary_hostname
str

主终结点的主机名。

方法

close

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

在指定的帐户下创建新的文件系统。

如果已存在同名的文件系统，则会引发 ResourceExistsError。 此方法返回与新创建的文件系统交互的客户端。
delete_file_system

标记要删除的指定文件系统。

稍后，在垃圾回收期间，将删除文件系统及其中包含的任何文件。 如果未找到文件系统，将引发 ResourceNotFoundError。
from_connection_string

从连接字符串创建 DataLakeServiceClient。

：return a DataLakeServiceClient ：rtype ~azure.storage.filedatalake.DataLakeServiceClient
get_directory_client

获取要与指定目录交互的客户端。

该目录不需要已经存在。
get_file_client

获取要与指定文件交互的客户端。

该文件不需要已经存在。
get_file_system_client

获取客户端以与指定的文件系统交互。

文件系统不需要已经存在。
get_service_properties

获取存储帐户的 datalake 服务的属性，包括 Azure 存储分析。

版本 12.4.0 中的新增功能：此操作是在 API 版本“2020-06-12”中引入的。
get_user_delegation_key

获取用于对 SAS 令牌进行签名的用户委派密钥。 服务对象上必须存在令牌凭据，此请求才能成功。
list_file_systems

返回一个生成器，用于列出指定帐户下的文件系统。

生成器将延迟跟踪服务返回的延续令牌，并在返回所有文件系统后停止。
set_service_properties

设置存储帐户的 Datalake 服务（包括 Azure 存储分析）的属性。

版本 12.4.0 中的新增功能：此操作是在 API 版本“2020-06-12”中引入的。

如果元素 (例如，analytics_logging) 保留为 None，则保留该服务上针对该功能的现有设置。
undelete_file_system

还原软删除的文件系统。

只有在删除保留策略中设置的指定天数内使用时，操作才会成功。

版本 12.3.0 中的新增功能：此操作是在 API 版本“2019-12-12”中引入的。

close

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

close() -> None

create_file_system

在指定的帐户下创建新的文件系统。

如果已存在同名的文件系统，则会引发 ResourceExistsError。 此方法返回与新创建的文件系统交互的客户端。

create_file_system(file_system: FileSystemProperties | str, metadata: Dict[str, str] | None = None, public_access: PublicAccess | None = None, **kwargs) -> FileSystemClient

参数

file_system
str
必需

要创建的文件系统的名称。

metadata
dict(str, str)
必需

具有名称/值对的 dict，这些名称/值对作为元数据与文件系统相关联。 示例： {'Category'：'test'}

public_access
PublicAccess
必需

可能的值包括：文件系统、文件。

encryption_scope_options
dict 或 EncryptionScopeOptions

指定要在文件系统上设置的默认加密范围，并将其用于将来的所有写入。

版本 12.9.0 中的新增功能。

timeout
int

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

返回类型

FileSystemClient

示例

在 datalake 服务中创建文件系统。


   datalake_service_client.create_file_system("filesystem")

delete_file_system

标记要删除的指定文件系统。

稍后，在垃圾回收期间，将删除文件系统及其中包含的任何文件。 如果未找到文件系统，将引发 ResourceNotFoundError。

delete_file_system(file_system: FileSystemProperties | str, **kwargs) -> FileSystemClient

参数

file_system
str 或 FileSystemProperties
必需

要删除的文件系统。 这可以是文件系统的名称，也可以是 FileSystemProperties 的实例。

lease
DataLakeLeaseClient 或 str

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

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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回类型

None

示例

删除 datalake 服务中的文件系统。


   datalake_service_client.delete_file_system("filesystem")

from_connection_string

从连接字符串创建 DataLakeServiceClient。

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

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

参数

conn_str
str
必需

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

credential
默认值: None

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

示例

从连接字符串创建 DataLakeServiceClient。


   from azure.storage.filedatalake import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

get_directory_client

获取要与指定目录交互的客户端。

该目录不需要已经存在。

get_directory_client(file_system: FileSystemProperties | str, directory: DirectoryProperties | str) -> DataLakeDirectoryClient

参数

file_system
str 或 FileSystemProperties
必需

目录位于的文件系统。 这可以是文件系统的名称，也可以是 FileSystemProperties 的实例。

directory
str 或 DirectoryProperties
必需

要与之交互的目录。 这可以是目录的名称，也可以是 DirectoryProperties 的实例。

返回

DataLakeDirectoryClient。

返回类型

DataLakeDirectoryClient

示例

让目录客户端与特定目录交互。


   directory_client = datalake_service_client.get_directory_client(file_system_client.file_system_name,
                                                                   "mydirectory")

get_file_client

获取要与指定文件交互的客户端。

该文件不需要已经存在。

get_file_client(file_system: FileSystemProperties | str, file_path: FileProperties | str) -> DataLakeFileClient

参数

file_system
str 或 FileSystemProperties
必需

文件位于的文件系统。 这可以是文件系统的名称，也可以是 FileSystemProperties 的实例。

file_path
str 或 FileProperties
必需

要与之交互的文件。 这可以是从根目录) (的文件的完整路径，也可以是 FileProperties 的实例。例如directory/subdirectory/file

返回

DataLakeFileClient。

返回类型

DataLakeFileClient

示例

获取文件客户端以与特定文件交互。


   file_client = datalake_service_client.get_file_client(file_system_client.file_system_name, "myfile")

get_file_system_client

获取客户端以与指定的文件系统交互。

文件系统不需要已经存在。

get_file_system_client(file_system: FileSystemProperties | str) -> FileSystemClient

参数

file_system
str 或 FileSystemProperties
必需

文件系统。 这可以是文件系统的名称，也可以是 FileSystemProperties 的实例。

返回

FileSystemClient。

返回类型

FileSystemClient

示例

让文件系统客户端与特定文件系统交互。


   # Instantiate a DataLakeServiceClient using a connection string
   from azure.storage.filedatalake import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

   # Instantiate a FileSystemClient
   file_system_client = datalake_service_client.get_file_system_client("mynewfilesystem")

get_service_properties

获取存储帐户的 datalake 服务的属性，包括 Azure 存储分析。

版本 12.4.0 中的新增功能：此操作是在 API 版本“2020-06-12”中引入的。

get_service_properties(**kwargs: Any) -> Dict[str, Any]

参数

timeout
int

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

返回

包含数据湖服务属性（例如分析日志记录、小时/分钟指标、cors 规则等）的 对象。

返回类型

Dict[str, Any]

get_user_delegation_key

获取用于对 SAS 令牌进行签名的用户委派密钥。 服务对象上必须存在令牌凭据，此请求才能成功。

get_user_delegation_key(key_start_time: datetime, key_expiry_time: datetime, **kwargs: Any) -> UserDelegationKey

参数

key_start_time
datetime
必需

一个日期时间值。 指示密钥何时变为有效。

key_expiry_time
datetime
必需

一个日期时间值。 指示密钥何时停止有效。

timeout
int

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

返回

用户委派密钥。

返回类型

UserDelegationKey

示例

从 datalake 服务客户端获取用户委派密钥。


   from datetime import datetime, timedelta
   user_delegation_key = datalake_service_client.get_user_delegation_key(datetime.utcnow(),
                                                                         datetime.utcnow() + timedelta(hours=1))

list_file_systems

返回一个生成器，用于列出指定帐户下的文件系统。

生成器将延迟跟踪服务返回的延续令牌，并在返回所有文件系统后停止。

list_file_systems(name_starts_with: str | None = None, include_metadata: bool | None = None, **kwargs) -> ItemPaged[FileSystemProperties]

参数

name_starts_with
str
必需

筛选结果以仅返回名称以指定前缀开头的文件系统。

include_metadata
bool
必需

指定在响应中返回文件系统元数据。 默认值为 False。

results_per_page
int

每个 API 调用要检索的最大文件系统名称数。 如果请求未指定，服务器将返回每页最多 5,000 个项目。

timeout
int

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

include_deleted
bool

指定要在响应中返回的已删除文件系统。 这适用于已启用文件系统还原的帐户。 默认值为 False。 .. versionadded：： 12.3.0

include_system
bool

指定应包含系统文件系统的标志。 .. versionadded：： 12.6.0

返回

FileSystemProperties 的可迭代 (自动分页) 。

返回类型

ItemPaged[FileSystemProperties]

示例

列出 datalake 服务中的文件系统。


   file_systems = datalake_service_client.list_file_systems()
   for file_system in file_systems:
       print(file_system.name)

set_service_properties

设置存储帐户的 Datalake 服务（包括 Azure 存储分析）的属性。

版本 12.4.0 中的新增功能：此操作是在 API 版本“2020-06-12”中引入的。

如果元素 (例如，analytics_logging) 保留为 None，则保留该服务上针对该功能的现有设置。

set_service_properties(**kwargs: Any) -> None

参数

analytics_logging

对 Azure Analytics Logging 设置进行分组。

hour_metrics

小时指标设置提供按 API 按小时聚合分组的请求统计信息的摘要。

minute_metrics

分钟指标设置提供每分钟的请求统计信息。

cors

列表中最多可以包含五个 CorsRule 元素。 如果指定了空列表，则将删除所有 CORS 规则，并且将禁用该服务的 CORS。

target_version
str

指示如果未指定传入请求的版本，则用于请求的默认版本。

delete_retention_policy

删除保留策略指定是否保留已删除的文件/目录。 它还指定要保留的文件/目录的天数和版本。

static_website

指定是否启用静态网站功能，如果是，则指示要使用的索引文档和 404 错误文档。

timeout
int

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

返回类型

None

undelete_file_system

还原软删除的文件系统。

只有在删除保留策略中设置的指定天数内使用时，操作才会成功。

版本 12.3.0 中的新增功能：此操作是在 API 版本“2019-12-12”中引入的。

undelete_file_system(name: str, deleted_version: str, **kwargs: Any) -> FileSystemClient

参数

name
str
必需

指定要还原的已删除文件系统的名称。

deleted_version
str
必需

指定要还原的已删除文件系统的版本。

timeout
int

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

返回

还原的 solft-deleted FileSystemClient。

返回类型

FileSystemClient

属性

api_version

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

location_mode

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

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

primary_endpoint

完整的主终结点 URL。

primary_hostname

主终结点的主机名。

secondary_endpoint

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

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

例外

ValueError

secondary_hostname

辅助终结点的主机名。

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

url

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

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