Share via

Usar o Python para gerenciar diretórios e arquivos no Azure Data Lake Storage Gen2

  • Artigo

Este artigo mostra como usar o Python para criar e gerenciar diretórios e arquivos nas contas de armazenamento que têm um namespace hierárquico.

Para saber mais sobre como obter, definir e atualizar as ACLs (listas de controle de acesso) de diretórios e arquivos, confira Usar o Python para gerenciar ACLs no Azure Data Lake Storage Gen2.

Pacote (PyPI) | Amostras | Referência de API | Mapeamento de Gen1 para Gen2 | Fornecer comentários

Pré-requisitos

Configurar o seu projeto

Esta seção fornece instruções sobre como preparar um projeto para funcionar com a biblioteca de clientes do Azure Data Lake Storage para Python.

No diretório do projeto, instale pacotes para as bibliotecas de cliente do Azure Data Lake Storage e do Azure Identity usando o comando pip install. O pacote azure-identity é necessário para conexões sem senha com os serviços do Azure.

pip install azure-storage-file-datalake azure-identity

Em seguida, abra o arquivo de código e adicione as instruções de importação necessárias. Neste exemplo, adicionamos o seguinte ao nosso arquivo .py:

import os
from azure.storage.filedatalake import (
    DataLakeServiceClient,
    DataLakeDirectoryClient,
    FileSystemClient
)
from azure.identity import DefaultAzureCredential

Observação

O acesso a vários protocolos no Data Lake Storage permite que os aplicativos usem APIs de Blob e APIs do Data Lake Storage Gen2 para trabalhar com dados em contas de armazenamento com o namespace hierárquico (HNS) habilitado. Ao trabalhar com recursos exclusivos do Data Lake Storage Gen2, como operações de diretório e ACLs, use as APIs do Data Lake Storage Gen2, conforme mostrado neste artigo.

Ao escolher quais APIs usar em um determinado cenário, considere a carga de trabalho e as necessidades do aplicativo, juntamente com os problemas conhecidos e o impacto do HNS em cargas de trabalho e aplicativos.

Autorizar o acesso e conectar-se a recursos de dados

Para trabalhar com os exemplos de código neste artigo, você precisa criar uma instância de DataLakeServiceClient autorizada que represente a conta de armazenamento. Você pode autorizar um objeto DataLakeServiceClient usando o Microsoft Entra ID, uma chave de acesso de conta ou uma Assinatura de Acesso Compartilhado (SAS).

Você pode usar a Biblioteca de clientes de identidade do Azure para Python para autenticar seu aplicativo com a ID do Microsoft Entra.

Crie uma instância da classe DataLakeServiceClient e passe um objeto DefaultAzureCredential.

def get_service_client_token_credential(self, account_name) -> DataLakeServiceClient:
    account_url = f"https://{account_name}.dfs.core.windows.net"
    token_credential = DefaultAzureCredential()

    service_client = DataLakeServiceClient(account_url, credential=token_credential)

    return service_client

Para saber mais sobre como usar DefaultAzureCredential para autorizar o acesso aos dados, confira Visão geral: autenticar aplicativos Python no Azure usando o SDK do Azure.

Criar um contêiner

Um contêiner atua como um sistema de arquivos para seus arquivos. Você pode criar um contêiner usando o método a seguir:

O exemplo de código a seguir cria um contêiner e retorna um objeto FileSystemClient para uso posterior:

def create_file_system(self, service_client: DataLakeServiceClient, file_system_name: str) -> FileSystemClient:
    file_system_client = service_client.create_file_system(file_system=file_system_name)

    return file_system_client

Criar um diretório

Você pode criar uma referência de diretório no contêiner usando o método a seguir:

O exemplo de código a seguir adiciona um diretório a um contêiner e retorna um objeto DataLakeDirectoryClient para uso posterior:

def create_directory(self, file_system_client: FileSystemClient, directory_name: str) -> DataLakeDirectoryClient:
    directory_client = file_system_client.create_directory(directory_name)

    return directory_client

Renomear ou mover um diretório

Você pode renomear ou mover um diretório usando o método a seguir:

Passe o caminho com o novo nome do diretório no argumento new_name. O valor deve ter o seguinte formato: {filesystem}/{directory}/{subdirectory}.

O exemplo de código a seguir mostra como renomear um subdiretório:

def rename_directory(self, directory_client: DataLakeDirectoryClient, new_dir_name: str):
    directory_client.rename_directory(
        new_name=f"{directory_client.file_system_name}/{new_dir_name}")

Carregar um arquivo em um diretório

Você pode carregar conteúdo em um arquivo novo ou existente usando o método a seguir:

O exemplo de código a seguir mostra como carregar um arquivo local para um diretório usando o método upload_data:

def upload_file_to_directory(self, directory_client: DataLakeDirectoryClient, local_path: str, file_name: str):
    file_client = directory_client.get_file_client(file_name)

    with open(file=os.path.join(local_path, file_name), mode="rb") as data:
        file_client.upload_data(data, overwrite=True)

Você pode usar esse método para criar e carregar conteúdos em um novo arquivo ou pode definir o argumento overwrite como True para substituir um arquivo existente.

Acrescentar dados a um arquivo

Você pode carregar os dados que serão acrescentados a um arquivo usando o seguinte método:

O exemplo de código a seguir mostra como acrescentar dados ao final de um arquivo usando estas etapas:

  • Crie um objeto DataLakeFileClient para representar o recurso do arquivo com o qual você está trabalhando.
  • Carregue dados no arquivo usando o método append_data.
  • Conclua o carregamento chamando o método flush_data para gravar os dados carregados anteriormente no arquivo.
def append_data_to_file(self, directory_client: DataLakeDirectoryClient, file_name: str):
    file_client = directory_client.get_file_client(file_name)
    file_size = file_client.get_file_properties().size
    
    data = b"Data to append to end of file"
    file_client.append_data(data, offset=file_size, length=len(data))

    file_client.flush_data(file_size + len(data))

Com esse método, os dados só podem ser acrescentados a um arquivo e a operação é limitada a 4.000 MiB por solicitação.

Baixar de um diretório

O exemplo de código a seguir mostra como baixar um arquivo de um diretório para um arquivo local usando estas etapas:

  • Crie um objeto DataLakeFileClient para representar o arquivo que você deseja baixar.
  • Abra um arquivo local para gravação.
  • Chame o método DataLakeFileClient.download_file para ler bytes do arquivo e, em seguida, gravar esses dados no arquivo local.
def download_file_from_directory(self, directory_client: DataLakeDirectoryClient, local_path: str, file_name: str):
    file_client = directory_client.get_file_client(file_name)

    with open(file=os.path.join(local_path, file_name), mode="wb") as local_file:
        download = file_client.download_file()
        local_file.write(download.readall())
        local_file.close()

Listar conteúdo do diretório

Você pode listar o conteúdo do diretório usando o método a seguir e enumerando o resultado:

A enumeração dos caminhos no resultado pode fazer várias solicitações ao serviço durante a busca dos valores.

O código de exemplo a seguir imprime o caminho de cada subdiretório e arquivo localizado em um diretório:

def list_directory_contents(self, file_system_client: FileSystemClient, directory_name: str):
    paths = file_system_client.get_paths(path=directory_name)

    for path in paths:
        print(path.name + '\n')

Excluir um diretório

Você pode excluir um diretório usando o método a seguir:

O exemplo de código a seguir mostra como excluir um diretório:

def delete_directory(self, directory_client: DataLakeDirectoryClient):
    directory_client.delete_directory()

Confira também