共用方式為

DataLakeServiceClient 類別

  • 參考

在帳戶層級與 DataLake 服務互動的用戶端。

此用戶端提供作業來擷取和設定帳戶屬性，以及列出、建立和刪除帳戶內的檔案系統。 對於與特定檔案系統、目錄或檔案相關的作業，也可以使用 get_client 函式來擷取這些實體的用戶端。

繼承
azure.storage.filedatalake._shared.base_client_async.AsyncStorageAccountHostsMixin
DataLakeServiceClient
azure.storage.filedatalake._data_lake_service_client.DataLakeServiceClient
DataLakeServiceClient

建構函式

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

參數

account_url
str
必要

DataLake 儲存體帳戶的 URL。 URL 路徑中包含的任何其他實體 (例如檔案系統或檔案) 將會捨棄。 此 URL 可以選擇性地使用 SAS 權杖進行驗證。

credential
預設值: None

要用來驗證的認證。 如果帳戶 URL 已經有 SAS 權杖，則這是選擇性的。 此值可以是 SAS 權杖字串、來自 azure.core.credentials 的 AzureSasCredential 或 AzureNamedKeyCredential 的實例、帳戶共用存取金鑰，或來自 azure.identity 的 TokenCredentials 類別實例。 如果資源 URI 已經包含 SAS 權杖，則會忽略此權杖，以取得明確的認證

  • 除了 AzureSasCredential 的情況之外，衝突的 SAS 權杖將會引發 ValueError。 如果使用 AzureNamedKeyCredential 的實例，「name」 應該是儲存體帳戶名稱，而 「key」 應該是儲存體帳戶金鑰。
api_version
str

要用於要求的儲存體 API 版本。 預設值是與目前 SDK 相容的最新服務版本。 將 設定為較舊版本可能會導致功能相容性降低。

範例

從連接字串建立 DataLakeServiceClient。


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

使用 Azure 身分識別認證建立 DataLakeServiceClient。


   from azure.identity.aio import ClientSecretCredential
   token_credential = ClientSecretCredential(
       active_directory_tenant_id,
       active_directory_application_id,
       active_directory_application_secret,
   )
   datalake_service_client = DataLakeServiceClient("https://{}.dfs.core.windows.net".format(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。

：傳回 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 儲存體分析。

如果專案 (例如，analytics_logging) 保留為 None，則會保留該服務上的現有設定。

12.4.0 版的新功能：此作業是在 API 版本 '2020-06-12' 中引進。
undelete_file_system

還原虛刪除的檔案系統。

只有在刪除保留原則中指定的天數內使用時，作業才會成功。

12.3.0 版的新功能：此作業是在 API 版本 '2019-12-12' 中引進。

close

這個方法是關閉用戶端所開啟的通訊端。 搭配內容管理員使用時，不需要使用它。

async close() -> None

create_file_system

在指定的帳號下建立新的檔案系統。

如果具有相同名稱的檔案系統已經存在，將會引發 ResourceExistsError。 這個方法會傳回要與新建立檔案系統互動的用戶端。

async 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)
必要

具有名稱/值組的聽寫，用來與檔案系統建立關聯為中繼資料。 範例： {'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 服務中建立檔案系統。


   await datalake_service_client.create_file_system("filesystem")

delete_file_system

標記要刪除的指定檔案系統。

檔案系統及其內含的任何檔案稍後會在垃圾收集期間刪除。 如果找不到檔案系統，將會引發 ResourceNotFoundError。

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

參數

file_system
str 或 FileSystemProperties
必要

要刪除的檔案系統。 這可以是檔案系統的名稱或 FileSystemProperties 的實例。

lease
DataLakeLeaseClient 或 str

如果指定，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 服務中的檔案系統。


   await datalake_service_client.delete_file_system("filesystem")

from_connection_string

從連接字串建立 DataLakeServiceClient。

：傳回 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.aio import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

   async with datalake_service_client:
       # Instantiate a FileSystemClient
       file_system_client = datalake_service_client.get_file_system_client("mynewfilesystems")

get_service_properties

取得儲存體帳戶之 Datalake 服務的屬性，包括 Azure 儲存體分析。

12.4.0 版的新功能：此作業是在 API 版本 '2020-06-12' 中引進。

async 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 權杖。 權杖認證必須存在於服務物件上，此要求才能成功。

async 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 = await 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()
   async for file_system in file_systems:
       print(file_system.name)

set_service_properties

設定儲存體帳戶 Datalake 服務的屬性，包括 Azure 儲存體分析。

如果專案 (例如，analytics_logging) 保留為 None，則會保留該服務上的現有設定。

12.4.0 版的新功能：此作業是在 API 版本 '2020-06-12' 中引進。

async set_service_properties(**kwargs: Any) -> None

參數

analytics_logging

將 Azure Analytics 記錄設定分組。

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 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

undelete_file_system

還原虛刪除的檔案系統。

只有在刪除保留原則中指定的天數內使用時，作業才會成功。

12.3.0 版的新功能：此作業是在 API 版本 '2019-12-12' 中引進。

async 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 。 用戶端上不會追蹤或驗證此值。 若要設定用戶端網路逾時，請參閱 這裡。

傳回

已還原虛刪除檔案系統的 FileSystemClient。

傳回類型

FileSystemClient

屬性

api_version

用於要求的儲存體 API 版本。

location_mode

用戶端目前使用的位置模式。

根據預設，這會是「主要」。 選項包括 「primary」 和 「secondary」。

primary_endpoint

完整的主要端點 URL。

primary_hostname

主要端點的主機名稱。

secondary_endpoint

如果已設定，則為完整的次要端點 URL。

如果無法使用，將會引發 ValueError。 若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

例外狀況

ValueError

secondary_hostname

次要端點的主機名稱。

如果無法使用，則為 None。 若要明確指定次要主機名稱，請在具現化上使用選擇性 secondary_hostname 關鍵字引數。

url

此實體的完整端點 URL，包括使用 SAS 權杖。

這可能是主要端點或次要端點，視目前的 location_mode 而定。 ：returns：使用此實體的完整端點 URL，包括使用 SAS 權杖。 ：rtype： str