Compartilhar via

DataLakeServiceClient Classe

  • Referência

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

Esse cliente fornece operações para recuperar e configurar as propriedades da conta, bem como listar, criar e excluir sistemas de arquivos dentro da conta. Para operações relacionadas a um sistema de arquivos específico, diretório ou arquivo, os clientes dessas entidades também podem ser recuperados usando 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
Obrigatório

A URL para a conta de armazenamento do DataLake. Todas as outras entidades incluídas no caminho da URL (por exemplo, sistema de arquivos ou arquivo) serão descartadas. Essa URL pode ser autenticada opcionalmente com um token SAS.

credential
valor padrão: None

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

  • exceto no caso de AzureSasCredential, em que os tokens SAS conflitantes gerarão um ValueError. Se estiver usando uma instância de AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.
api_version
str

A versão da API de Armazenamento a ser usada para solicitações. O valor padrão é a versão de serviço mais recente compatível com o SDK atual. A configuração para uma versão mais antiga pode resultar em redução da compatibilidade de recursos.

Exemplos

Criando o DataLakeServiceClient da cadeia de conexão.


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

Criando 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

A URL completa do ponto de extremidade para o ponto de extremidade de serviço datalake.

primary_endpoint
str

A URL completa do ponto de extremidade primário.

primary_hostname
str

O nome do host do ponto de extremidade primário.

Métodos

close

Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.
create_file_system

Cria um novo sistema de arquivos na conta especificada.

Se o sistema de arquivos com o mesmo nome já existir, um ResourceExistsError será gerado. Esse método retorna um cliente com o qual interagir com o sistema de arquivos recém-criado.
delete_file_system

Marca o sistema de arquivos especificado para exclusão.

O sistema de arquivos e todos os arquivos contidos nele serão excluídos posteriormente durante a coleta de lixo. Se o sistema de arquivos não for encontrado, um ResourceNotFoundError será gerado.
from_connection_string

Crie DataLakeServiceClient de uma cadeia de conexã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 existir.
get_file_client

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

O arquivo ainda não precisa existir.
get_file_system_client

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

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

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

Novo na versão 12.4.0: essa operação foi introduzida na versão da API '2020-06-12'.
get_user_delegation_key

Obtenha uma chave de delegação de usuário com a finalidade de assinar tokens SAS. Uma credencial de token deve estar presente no objeto de serviço para que essa solicitação tenha êxito.
list_file_systems

Retorna um gerador para listar os sistemas de arquivos na conta especificada.

O gerador seguirá lentamente os tokens de continuação retornados pelo serviço e será interrompido quando todos os sistemas de arquivos forem retornados.
set_service_properties

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

Novo na versão 12.4.0: essa operação foi introduzida na versão da API '2020-06-12'.

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

Restaura o sistema de arquivos com exclusão reversível.

A operação só será bem-sucedida se for usada dentro do número especificado de dias definido na política de retenção de exclusão.

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

close

Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.

close() -> None

create_file_system

Cria um novo sistema de arquivos na conta especificada.

Se o sistema de arquivos com o mesmo nome já existir, um ResourceExistsError será gerado. Esse método retorna um cliente com o qual interagir com o sistema de arquivos recém-criado.

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
Obrigatório

O nome do sistema de arquivos a ser criado.

metadata
dict(str, str)
Obrigatório

Um dict com pares nome-valor a serem associados ao sistema de arquivos como metadados. Exemplo: {'Category':'test'}

public_access
PublicAccess
Obrigatório

Os valores possíveis incluem: sistema de arquivos, arquivo.

encryption_scope_options
dict ou EncryptionScopeOptions

Especifica o escopo de criptografia padrão a ser definido no sistema de arquivos e usado para todas as gravações futuras.

Novo 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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, consulte aqui.

Tipo de retorno

FileSystemClient

Exemplos

Criando um sistema de arquivos no serviço datalake.


   datalake_service_client.create_file_system("filesystem")

delete_file_system

Marca o sistema de arquivos especificado para exclusão.

O sistema de arquivos e todos os arquivos contidos nele serão excluídos posteriormente durante a coleta de lixo. Se o sistema de arquivos não for encontrado, um ResourceNotFoundError será gerado.

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

Parâmetros

file_system
str ou FileSystemProperties
Obrigatório

O sistema de arquivos a ser excluído. Pode ser o nome do sistema de arquivos ou uma instância de FileSystemProperties.

lease
DataLakeLeaseClient ou str

Se especificado, delete_file_system só terá êxito se a concessão do sistema de arquivos estiver ativa e corresponder a essa ID. Obrigatório se o sistema de arquivos tiver uma concessão ativa.

if_modified_since
datetime

Um valor Datetime. O Azure espera que o valor de data passado seja UTC. Se o fuso horário for incluído, todos os datetimes não UTC serão convertidos em UTC. Se uma data for passada sem informações de fuso horário, será considerado UTC. Especifique esse cabeçalho para executar a operação somente 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 passado seja UTC. Se o fuso horário for incluído, todos os datetimes não UTC serão convertidos em UTC. Se uma data for passada sem informações de fuso horário, será considerado UTC. Especifique esse cabeçalho para executar a operação somente se o recurso não tiver sido modificado desde a data/hora especificada.

etag
str

Um valor de ETag ou o caractere curinga (*). Usado para marcar 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 ser usada na etag.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, consulte aqui.

Tipo de retorno

None

Exemplos

Excluindo um sistema de arquivos no serviço datalake.


   datalake_service_client.delete_file_system("filesystem")

from_connection_string

Crie DataLakeServiceClient de uma cadeia de conexã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
Obrigatório

Uma cadeia de conexão para uma conta de Armazenamento do Azure.

credential
valor padrão: None

As credenciais com as quais autenticar. Isso é opcional se a URL da conta já tiver um token SAS ou se a cadeia de conexão já tiver valores de chave de acesso compartilhados. O valor pode ser uma cadeia de caracteres de token SAS, uma instância de um AzureSasCredential de azure.core.credentials, uma chave de acesso compartilhado de conta ou uma instância de uma classe TokenCredentials de azure.identity. As credenciais fornecidas aqui terão precedência sobre aquelas na cadeia de conexão.

Exemplos

Criando o DataLakeServiceClient de uma cadeia de conexã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 existir.

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

Parâmetros

file_system
str ou FileSystemProperties
Obrigatório

O sistema de arquivos no qual o diretório está. Pode ser o nome do sistema de arquivos ou uma instância de FileSystemProperties.

directory
str ou DirectoryProperties
Obrigatório

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

Retornos

Um DataLakeDirectoryClient.

Tipo de retorno

DataLakeDirectoryClient

Exemplos

Fazer com que o cliente de 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 arquivo especificado.

O arquivo ainda não precisa existir.

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

Parâmetros

file_system
str ou FileSystemProperties
Obrigatório

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

file_path
str ou FileProperties
Obrigatório

O arquivo com o qual interagir. Esse pode ser o caminho completo do arquivo (do diretório raiz) ou uma instância de FileProperties. Eg. directory/subdirectory/file

Retornos

Um DataLakeFileClient.

Tipo de retorno

DataLakeFileClient

Exemplos

Fazer com que o cliente do arquivo interaja com um arquivo 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 arquivos especificado.

O sistema de arquivos ainda não precisa existir.

get_file_system_client(file_system: FileSystemProperties | str) -> FileSystemClient

Parâmetros

file_system
str ou FileSystemProperties
Obrigatório

O sistema de arquivos. Esse pode ser o nome do sistema de arquivos ou uma instância de FileSystemProperties.

Retornos

Um FileSystemClient.

Tipo de retorno

FileSystemClient

Exemplos

Fazer com que o cliente do sistema de arquivos interaja com um sistema de arquivos 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 Análise de Armazenamento do Azure.

Novo na versão 12.4.0: essa 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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

Retornos

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

Tipo de retorno

Dict[str, Any]

get_user_delegation_key

Obtenha uma chave de delegação de usuário com a finalidade de assinar tokens SAS. Uma credencial de token deve estar presente no objeto de serviço para que essa solicitação tenha êxito.

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

Parâmetros

key_start_time
datetime
Obrigatório

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

key_expiry_time
datetime
Obrigató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 informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

Retornos

A chave de delegação do usuário.

Tipo de retorno

UserDelegationKey

Exemplos

Obtenha a chave de delegação do usuário do cliente de 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

Retorna um gerador para listar os sistemas de arquivos na conta especificada.

O gerador seguirá lentamente os tokens de continuação retornados pelo serviço e será interrompido quando todos os sistemas de arquivos forem retornados.

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

Parâmetros

name_starts_with
str
Obrigatório

Filtra os resultados para retornar somente sistemas de arquivos cujos nomes começam com o prefixo especificado.

include_metadata
bool
Obrigatório

Especifica que os metadados do sistema de arquivos sejam retornados na resposta. O valor padrão é Falso.

results_per_page
int

O número máximo de nomes do sistema de arquivos a serem recuperados por chamada à API. Se a solicitação não especificar, o servidor retornará até 5.000 itens por página.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

include_deleted
bool

Especifica que os sistemas de arquivos excluídos a serem retornados na resposta. Isso é para a conta habilitada para restauração do sistema de arquivos. O valor padrão é Falso. .. versionadded:: 12.3.0

include_system
bool

Sinalizador especificando que os sistemas de arquivos do sistema devem ser incluídos. .. versionadded:: 12.6.0

Retornos

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

Tipo de retorno

ItemPaged[FileSystemProperties]

Exemplos

Listando os sistemas de arquivos 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 Análise de Armazenamento do Azure.

Novo na versão 12.4.0: essa operação foi introduzida na versão da API '2020-06-12'.

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

set_service_properties(**kwargs: Any) -> None

Parâmetros

analytics_logging

Agrupa as configurações de Log da Análise do Azure.

hour_metrics

As configurações de métricas de hora fornecem um resumo das estatísticas de solicitação agrupadas pela API em agregações por hora.

minute_metrics

As configurações de métricas de minuto fornecem estatísticas de solicitação para cada minuto.

cors

Você pode incluir até cinco elementos CorsRule na lista. Se uma lista vazia for especificada, todas as regras CORS serão excluídas e o CORS será desabilitado para o serviço.

target_version
str

Indica a versão padrão a ser usada para solicitações se a versão de uma solicitação de entrada não for especificada.

delete_retention_policy

A política de retenção de exclusão especifica se os arquivos/diretórios excluídos devem ser retidos. Ele também especifica o número de dias e versões do arquivo/diretório a serem mantidos.

static_website

Especifica se o recurso de site estático está habilitado e, se sim, indica o documento de índice e o documento de erro 404 a ser usado.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

Tipo de retorno

None

undelete_file_system

Restaura o sistema de arquivos com exclusão reversível.

A operação só será bem-sucedida se for usada dentro do número especificado de dias definido na política de retenção de exclusão.

Novidade na versão 12.3.0: essa 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
Obrigatório

Especifica o nome do sistema de arquivos excluído a ser restaurado.

deleted_version
str
Obrigatório

Especifica a versão do sistema de arquivos excluído a ser restaurado.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais informações, confira https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, confira aqui.

Retornos

O FileSystemClient excluído por solft restaurado.

Tipo de retorno

FileSystemClient

Atributos

api_version

A versão da API de Armazenamento usada para solicitações.

location_mode

O modo de localização que o cliente está usando no momento.

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

primary_endpoint

A URL completa do ponto de extremidade primário.

primary_hostname

O nome do host do ponto de extremidade primário.

secondary_endpoint

A URL completa do ponto de extremidade secundário, se configurada.

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

Exceções

ValueError

secondary_hostname

O nome do host do ponto de extremidade secundário.

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

url

A URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado.

Isso pode ser o ponto de extremidade primário ou o ponto de extremidade secundário, dependendo do atual location_mode. :returns: a URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado. :rtype: str