Partilhar via

DataLakeServiceClient Classe

  • Referência

Um cliente para interagir com o Serviço DataLake ao nível da conta.

Este cliente fornece operações para obter e configurar as propriedades da conta, bem como listar, criar e eliminar sistemas de ficheiros na conta. Para operações relacionadas com um sistema de ficheiros, diretório ou ficheiro específico, os clientes dessas entidades também podem ser obtidos com as funções get_client .

Herança
azure.storage.filedatalake._shared.base_client.StorageAccountHostsMixin
DataLakeServiceClient

Construtor

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

Parâmetros

account_url
str
Necessário

O URL para a conta de armazenamento dataLake. Quaisquer outras entidades incluídas no caminho do URL (por exemplo, sistema de ficheiros ou ficheiro) serão eliminadas. Opcionalmente, este URL pode ser autenticado com um token de SAS.

credential
valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS. O valor pode ser uma cadeia de token de SAS, uma instância de uma AzureSasCredential ou AzureNamedKeyCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. Se o URI do recurso já contiver um token de SAS, este será ignorado a favor de uma credencial explícita

  • exceto no caso do AzureSasCredential, em que os tokens SAS em conflito gerarão um ValueError. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.
api_version
str

A versão da API de Armazenamento a utilizar para pedidos. O valor predefinido é a versão de serviço mais recente compatível com o SDK atual. Definir para uma versão mais antiga pode resultar numa compatibilidade de funcionalidades reduzida.

Exemplos

Criar o DataLakeServiceClient a partir da cadeia de ligação.


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

Criar o DataLakeServiceClient com credenciais de Identidade do Azure.


   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)

Variáveis

url
str

O URL de ponto final completo para o ponto final de serviço do datalake.

primary_endpoint
str

O URL do ponto final primário completo.

primary_hostname
str

O nome do anfitrião do ponto final primário.

Métodos

close

Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-lo ao utilizar com um gestor de contexto.
create_file_system

Cria um novo sistema de ficheiros na conta especificada.

Se o sistema de ficheiros com o mesmo nome já existir, será gerado um ResourceExistsError. Este método devolve um cliente com o qual pode interagir com o sistema de ficheiros criado recentemente.
delete_file_system

Marca o sistema de ficheiros especificado para eliminação.

O sistema de ficheiros e quaisquer ficheiros nele contidos são posteriormente eliminados durante a recolha de lixo. Se o sistema de ficheiros não for encontrado, será gerado um ResourceNotFoundError.
from_connection_string

Crie DataLakeServiceClient a partir de uma Cadeia de Ligação.

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

Faça com que um cliente interaja com o diretório especificado.

O diretório ainda não precisa de existir.
get_file_client

Faça com que um cliente interaja com o ficheiro especificado.

O ficheiro ainda não precisa de existir.
get_file_system_client

Faça com que um cliente interaja com o sistema de ficheiros especificado.

O sistema de ficheiros ainda não precisa de existir.
get_service_properties

Obtém as propriedades do serviço datalake de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.

Novidade na versão 12.4.0: esta operação foi introduzida na versão da API "2020-06-12".
get_user_delegation_key

Obtenha uma chave de delegação de utilizador para fins de assinatura de tokens DE SAS. Tem de estar presente uma credencial de token no objeto de serviço para que este pedido seja bem-sucedido.
list_file_systems

Devolve um gerador para listar os sistemas de ficheiros na conta especificada.

O gerador seguirá preguiçosamente os tokens de continuação devolvidos pelo serviço e parará quando todos os sistemas de ficheiros tiverem sido devolvidos.
set_service_properties

Define as propriedades do serviço Datalake de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.

Novidade na versão 12.4.0: esta operação foi introduzida na versão da API "2020-06-12".

Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as definições existentes no serviço para essa funcionalidade serão preservadas.
undelete_file_system

Restaura o sistema de ficheiros eliminado de forma recuperável.

A operação só será bem-sucedida se for utilizada no número especificado de dias definido na política de retenção de eliminação.

Novidade na versão 12.3.0: esta operação foi introduzida na versão da API "2019-12-12".

close

Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-lo ao utilizar com um gestor de contexto.

close() -> None

create_file_system

Cria um novo sistema de ficheiros na conta especificada.

Se o sistema de ficheiros com o mesmo nome já existir, será gerado um ResourceExistsError. Este método devolve um cliente com o qual pode interagir com o sistema de ficheiros criado recentemente.

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

Parâmetros

file_system
str
Necessário

O nome do sistema de ficheiros a criar.

metadata
dict(str, str)
Necessário

Um ditado com pares nome-valor para associar ao sistema de ficheiros como metadados. Exemplo: {'Category':'test'}

public_access
PublicAccess
Necessário

Os valores possíveis incluem: sistema de ficheiros, ficheiro.

encryption_scope_options
dict ou EncryptionScopeOptions

Especifica o âmbito de encriptação predefinido a definir no sistema de ficheiros e a utilização para todas as escritas futuras.

Novidade na versão 12.9.0.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

FileSystemClient

Exemplos

Criar um sistema de ficheiros no serviço datalake.


   datalake_service_client.create_file_system("filesystem")

delete_file_system

Marca o sistema de ficheiros especificado para eliminação.

O sistema de ficheiros e quaisquer ficheiros nele contidos são posteriormente eliminados durante a recolha de lixo. Se o sistema de ficheiros não for encontrado, será gerado um ResourceNotFoundError.

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

Parâmetros

file_system
str ou FileSystemProperties
Necessário

O sistema de ficheiros a eliminar. Pode ser o nome do sistema de ficheiros ou uma instância de FileSystemProperties.

lease
DataLakeLeaseClient ou str

Se especificado, delete_file_system só é bem-sucedido se a concessão do sistema de ficheiros estiver ativa e corresponder a este ID. Necessário se o sistema de ficheiros tiver uma concessão ativa.

if_modified_since
datetime

Um valor DateTime. O Azure espera que o valor de data transmitido seja UTC. Se o fuso horário estiver incluído, quaisquer datetimes não UTC serão convertidos em UTC. Se uma data for transmitida sem informações de fuso horário, assume-se que é UTC. Especifique este cabeçalho para executar a operação apenas se o recurso tiver sido modificado desde a hora especificada.

if_unmodified_since
datetime

Um valor DateTime. O Azure espera que o valor de data transmitido seja UTC. Se o fuso horário estiver incluído, quaisquer datetimes não UTC serão convertidos em UTC. Se uma data for transmitida sem informações de fuso horário, assume-se que é UTC. Especifique este cabeçalho para executar a operação apenas se o recurso não tiver sido modificado desde a data/hora especificada.

etag
str

Um valor ETag ou o caráter universal (*). Utilizado para verificar se o recurso foi alterado e agir de acordo com a condição especificada pelo parâmetro match_condition .

match_condition
MatchConditions

A condição de correspondência a utilizar no etag.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

None

Exemplos

A eliminar um sistema de ficheiros no serviço datalake.


   datalake_service_client.delete_file_system("filesystem")

from_connection_string

Crie DataLakeServiceClient a partir de uma Cadeia de Ligação.

: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

Parâmetros

conn_str
str
Necessário

Uma cadeia de ligação a uma conta de Armazenamento do Azure.

credential
valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS ou se a cadeia de ligação já tiver valores de chave de acesso partilhados. O valor pode ser uma cadeia de token de SAS, uma instância de um AzureSasCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. As credenciais aqui fornecidas terão precedência sobre as da cadeia de ligação.

Exemplos

Criar o DataLakeServiceClient a partir de uma cadeia de ligação.


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

get_directory_client

Faça com que um cliente interaja com o diretório especificado.

O diretório ainda não precisa de existir.

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

Parâmetros

file_system
str ou FileSystemProperties
Necessário

O sistema de ficheiros em que se encontra o diretório. Pode ser o nome do sistema de ficheiros ou uma instância de FileSystemProperties.

directory
str ou DirectoryProperties
Necessário

O diretório com o qual interagir. Este pode ser o nome do diretório ou uma instância de DirectoryProperties.

Devoluções

A DataLakeDirectoryClient.

Tipo de retorno

DataLakeDirectoryClient

Exemplos

Fazer com que o cliente do diretório interaja com um diretório específico.


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

get_file_client

Faça com que um cliente interaja com o ficheiro especificado.

O ficheiro ainda não precisa de existir.

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

Parâmetros

file_system
str ou FileSystemProperties
Necessário

O sistema de ficheiros no qual o ficheiro está. Pode ser o nome do sistema de ficheiros ou uma instância de FileSystemProperties.

file_path
str ou FileProperties
Necessário

O ficheiro com o qual interagir. Este pode ser o caminho completo do ficheiro (do diretório de raiz) ou uma instância de FileProperties. por exemplo, diretório/subdiretório/ficheiro

Devoluções

Um DataLakeFileClient.

Tipo de retorno

DataLakeFileClient

Exemplos

Fazer com que o cliente de ficheiros interaja com um ficheiro específico.


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

get_file_system_client

Faça com que um cliente interaja com o sistema de ficheiros especificado.

O sistema de ficheiros ainda não precisa de existir.

get_file_system_client(file_system: FileSystemProperties | str) -> FileSystemClient

Parâmetros

file_system
str ou FileSystemProperties
Necessário

O sistema de ficheiros. Pode ser o nome do sistema de ficheiros ou uma instância de FileSystemProperties.

Devoluções

Um FileSystemClient.

Tipo de retorno

FileSystemClient

Exemplos

Fazer com que o cliente do sistema de ficheiros interaja com um sistema de ficheiros específico.


   # 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

Obtém as propriedades do serviço datalake de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.

Novidade na versão 12.4.0: esta operação foi introduzida na versão da API "2020-06-12".

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

Parâmetros

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

Um objeto que contém propriedades do serviço datalake, tais como registo de análise, métricas de hora/minuto, regras cors, etc.

Tipo de retorno

Dict[str, Any]

get_user_delegation_key

Obtenha uma chave de delegação de utilizador para fins de assinatura de tokens DE SAS. Tem de estar presente uma credencial de token no objeto de serviço para que este pedido seja bem-sucedido.

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

Parâmetros

key_start_time
datetime
Necessário

Um valor DateTime. Indica quando a chave se torna válida.

key_expiry_time
datetime
Necessário

Um valor DateTime. Indica quando a chave deixa de ser válida.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

A chave de delegação do utilizador.

Tipo de retorno

UserDelegationKey

Exemplos

Obtenha a chave de delegação de utilizador do cliente do serviço 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

Devolve um gerador para listar os sistemas de ficheiros na conta especificada.

O gerador seguirá preguiçosamente os tokens de continuação devolvidos pelo serviço e parará quando todos os sistemas de ficheiros tiverem sido devolvidos.

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

Parâmetros

name_starts_with
str
Necessário

Filtra os resultados para devolver apenas sistemas de ficheiros cujos nomes começam com o prefixo especificado.

include_metadata
bool
Necessário

Especifica que os metadados do sistema de ficheiros são devolvidos na resposta. O valor predefinido é Falso.

results_per_page
int

O número máximo de nomes do sistema de ficheiros a obter por chamada à API. Se o pedido não especificar, o servidor devolverá até 5000 itens por página.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

include_deleted
bool

Especifica que os sistemas de ficheiros eliminados serão devolvidos na resposta. Isto destina-se à conta ativada para restauro do sistema de ficheiros. O valor predefinido é Falso. .. versionadded:: 12.3.0

include_system
bool

Sinalizador a especificar que os sistemas de ficheiros devem ser incluídos. .. versionadded:: 12.6.0

Devoluções

Uma iterável (paginação automática) de FileSystemProperties.

Tipo de retorno

ItemPaged[FileSystemProperties]

Exemplos

Listar os sistemas de ficheiros no serviço datalake.


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

set_service_properties

Define as propriedades do serviço Datalake de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.

Novidade na versão 12.4.0: esta operação foi introduzida na versão da API "2020-06-12".

Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as definições existentes no serviço para essa funcionalidade serão preservadas.

set_service_properties(**kwargs: Any) -> None

Parâmetros

analytics_logging

Agrupa as definições de Registo do Azure Analytics.

hour_metrics

As definições de métricas de hora fornecem um resumo das estatísticas de pedido agrupadas pela API em agregados por hora.

minute_metrics

As definições de métricas de minuto fornecem estatísticas de pedidos para cada minuto.

cors

Pode incluir até cinco elementos CorsRule na lista. Se for especificada uma lista vazia, todas as regras CORS serão eliminadas e o CORS será desativado para o serviço.

target_version
str

Indica a versão predefinida a utilizar para pedidos se a versão de um pedido de entrada não for especificada.

delete_retention_policy

A política de retenção eliminar especifica se pretende reter ficheiros/diretórios eliminados. Também especifica o número de dias e versões do ficheiro/diretório a manter.

static_website

Especifica se a funcionalidade de site estático estático está ativada e, se sim, indica o documento de índice e o documento de erro 404 a utilizar.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Tipo de retorno

None

undelete_file_system

Restaura o sistema de ficheiros eliminado de forma recuperável.

A operação só será bem-sucedida se for utilizada no número especificado de dias definido na política de retenção de eliminação.

Novidade na versão 12.3.0: esta operação foi introduzida na versão da API "2019-12-12".

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

Parâmetros

name
str
Necessário

Especifica o nome do sistema de ficheiros eliminado a restaurar.

deleted_version
str
Necessário

Especifica a versão do sistema de ficheiros eliminado a restaurar.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui.

Devoluções

O FileSystemClient restaurado eliminado por solft.

Tipo de retorno

FileSystemClient

Atributos

api_version

A versão da API de Armazenamento utilizada para pedidos.

location_mode

O modo de localização que o cliente está a utilizar atualmente.

Por predefinição, será "primário". As opções incluem "principal" e "secundário".

primary_endpoint

O URL do ponto final primário completo.

primary_hostname

O nome do anfitrião do ponto final primário.

secondary_endpoint

O URL completo do ponto final secundário, se configurado.

Se não estiver disponível, será gerado um ValueError. Para especificar explicitamente um nome de anfitrião secundário, utilize o argumento opcional secondary_hostname palavra-chave na instanciação.

Exceções

ValueError

secondary_hostname

O nome do anfitrião do ponto final secundário.

Se não estiver disponível, este será Nenhum. Para especificar explicitamente um nome de anfitrião secundário, utilize o argumento opcional secondary_hostname palavra-chave na instanciação.

url

O URL de ponto final completo para esta entidade, incluindo o token de SAS, se utilizado.

Este pode ser o ponto final principal ou o ponto final secundário, dependendo do atual location_mode. :returns: o URL de ponto final completo para esta entidade, incluindo o token SAS, se utilizado. :rtype: str