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

Artigo
04/09/2024

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

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

Pacote (Maven) | Exemplos | API referência | Gen1 para Gen2 mapeamento | Dar feedback

Pré-requisitos

Uma subscrição do Azure. Para obter mais informações, consulte Obter avaliação gratuita do Azure.
Uma conta de armazenamento com namespace hierárquico habilitado. Siga estas instruções para criar um.

Configure o seu projeto

Para começar, abra esta página e encontre a versão mais recente da biblioteca Java. Em seguida, abra o arquivo pom.xml no editor de texto. Adicione um elemento de dependência que faça referência a essa versão.

Se você planeja autenticar seu aplicativo cliente usando a ID do Microsoft Entra, adicione uma dependência à biblioteca de Identidade do Azure. Para obter mais informações, consulte Biblioteca de cliente do Azure Identity para Java.

Em seguida, adicione essas instruções imports ao seu arquivo de código.

import com.azure.identity.*;
import com.azure.storage.common.StorageSharedKeyCredential;
import com.azure.core.http.rest.PagedIterable;
import com.azure.core.util.BinaryData;
import com.azure.storage.file.datalake.*;
import com.azure.storage.file.datalake.models.*;
import com.azure.storage.file.datalake.options.*;

Nota

O acesso multiprotocolo 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 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 seu 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 DataLakeServiceClient autorizada que represente a conta de armazenamento. Você pode autorizar um objeto usando o DataLakeServiceClient Microsoft Entra ID, uma chave de acesso de conta ou uma assinatura de acesso compartilhado (SAS).

Você pode usar a biblioteca de cliente de identidade do Azure para Java para autenticar seu aplicativo com o Microsoft Entra ID.

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

static public DataLakeServiceClient GetDataLakeServiceClient(String accountName){
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
        .endpoint("https://" + accountName + ".dfs.core.windows.net")
        .credential(defaultCredential)
        .buildClient();

    return dataLakeServiceClient;
}

Para saber mais sobre como usar DefaultAzureCredential para autorizar o acesso a dados, consulte Biblioteca de cliente do Azure Identity para Java.

Para usar um token de assinatura de acesso compartilhado (SAS), forneça o token como uma cadeia de caracteres e inicialize um objeto DataLakeServiceClient . Se o URL da sua conta incluir o token SAS, omita o parâmetro credential.

static public DataLakeServiceClient GetDataLakeServiceClientSAS(String accountName, String sasToken){
    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
        .endpoint("https://" + accountName + ".dfs.core.windows.net")
        .sasToken(sasToken)
        .buildClient();

    return dataLakeServiceClient;
}

Para saber mais sobre como gerar e gerenciar tokens SAS, consulte o seguinte artigo:

Conceder acesso limitado aos recursos do Armazenamento do Azure com assinaturas de acesso partilhado (SAS)

Você pode autorizar o acesso aos dados usando as chaves de acesso da sua conta (Chave compartilhada). Este exemplo cria uma instância DataLakeServiceClient que é autorizada com a chave de conta.

static public DataLakeServiceClient GetDataLakeServiceClient
(String accountName, String accountKey){
    StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
        .endpoint("https://" + accountName + ".dfs.core.windows.net")
        .credential(sharedKeyCredential)
        .buildClient();

    return dataLakeServiceClient;
}

Atenção

A autorização com chave compartilhada não é recomendada, pois pode ser menos segura. Para uma segurança ideal, desative a autorização através da Chave Partilhada para a sua conta de armazenamento, conforme descrito em Impedir autorização de Chave Partilhada para uma conta de Armazenamento do Azure.

O uso de chaves de acesso e cadeias de conexão deve ser limitado a aplicativos de prova de conceito iniciais ou protótipos de desenvolvimento que não acessam dados confidenciais ou de produção. Caso contrário, as classes de autenticação baseada em token disponíveis no SDK do Azure devem sempre ser preferidas ao autenticar nos recursos do Azure.

A Microsoft recomenda que os clientes usem o Microsoft Entra ID ou uma assinatura de acesso compartilhado (SAS) para autorizar o acesso aos dados no Armazenamento do Azure. Para obter mais informações, consulte Autorizar operações para acesso a dados.

Criar um contentor

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

DataLakeServiceClient.createFileSystem

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

public DataLakeFileSystemClient CreateFileSystem(
        DataLakeServiceClient serviceClient,
        String fileSystemName) {

    DataLakeFileSystemClient fileSystemClient = serviceClient.createFileSystem(fileSystemName);

    return fileSystemClient;
}

Criar um diretório

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

DataLakeFileSystemClient.createDirectory

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

public DataLakeDirectoryClient CreateDirectory(
        DataLakeFileSystemClient fileSystemClient,
        String directoryName,
        String subDirectoryName) {

    DataLakeDirectoryClient directoryClient = fileSystemClient.createDirectory(directoryName);

    return directoryClient.createSubdirectory(subDirectoryName);
}

Renomear ou mover um diretório

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

DataLakeDirectoryClient.renomear

Passe o caminho do diretório desejado como um parâmetro. O exemplo de código a seguir mostra como renomear um subdiretório:

public DataLakeDirectoryClient RenameDirectory(
        DataLakeFileSystemClient fileSystemClient,
        String directoryPath,
        String subdirectoryName,
        String subdirectoryNameNew) {

    DataLakeDirectoryClient directoryClient = fileSystemClient
            .getDirectoryClient(String.join("/", directoryPath, subdirectoryName));

    return directoryClient.rename(
            fileSystemClient.getFileSystemName(),
            String.join("/", directoryPath, subdirectoryNameNew));
}

O exemplo de código a seguir mostra como mover um subdiretório de um diretório para um diretório diferente:

public DataLakeDirectoryClient MoveDirectory(
        DataLakeFileSystemClient fileSystemClient,
        String directoryPathFrom,
        String directoryPathTo,
        String subdirectoryName) {

    DataLakeDirectoryClient directoryClient = fileSystemClient
            .getDirectoryClient(String.join("/", directoryPathFrom, subdirectoryName));

    return directoryClient.rename(
            fileSystemClient.getFileSystemName(),
            String.join("/", directoryPathTo, subdirectoryName));
}

Carregar um ficheiro para um diretório

Você pode carregar conteúdo para um arquivo novo ou existente usando o seguinte método:

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

public void UploadFile(
        DataLakeDirectoryClient directoryClient,
        String fileName) {

    DataLakeFileClient fileClient = directoryClient.getFileClient(fileName);

    fileClient.uploadFromFile("filePath/sample-file.txt");
}

Você pode usar esse método para criar e carregar conteúdo para um novo arquivo ou pode definir o overwrite parâmetro para true substituir um arquivo existente.

Acrescentar dados a um ficheiro

Você pode carregar dados a serem anexados a um arquivo usando o seguinte método:

DataLakeFileClient.append

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

Crie um DataLakeFileClient objeto para representar o recurso de arquivo com o qual você está trabalhando.
Carregue dados para o arquivo usando o DataLakeFileClient.append método.
Conclua o upload chamando o DataLakeFileClient.flush método para gravar os dados carregados anteriormente no arquivo.

public void AppendDataToFile(
        DataLakeDirectoryClient directoryClient) {

    DataLakeFileClient fileClient = directoryClient.getFileClient("sample-file.txt");
    long fileSize = fileClient.getProperties().getFileSize();

    String sampleData = "Data to append to end of file";
    fileClient.append(BinaryData.fromString(sampleData), fileSize);

    fileClient.flush(fileSize + sampleData.length(), true);
}

Download 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 DataLakeFileClient objeto para representar o arquivo que você deseja baixar.
Use o DataLakeFileClient.readToFile método para ler o arquivo. Este exemplo define o overwrite parâmetro como true, que substitui um arquivo existente.

public void DownloadFile(
        DataLakeDirectoryClient directoryClient,
        String fileName) {

    DataLakeFileClient fileClient = directoryClient.getFileClient(fileName);

    fileClient.readToFile("filePath/sample-file.txt", true);
}

Listar conteúdo do diretório

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

DataLakeDirectoryClient.listPaths

Enumerar os caminhos no resultado pode fazer várias solicitações para o serviço ao buscar os valores.

O exemplo de código a seguir imprime os nomes de cada arquivo que está localizado em um diretório:

public void ListFilesInDirectory(
        DataLakeFileSystemClient fileSystemClient,
        String directoryName) {

    ListPathsOptions options = new ListPathsOptions();
    options.setPath(directoryName);

    PagedIterable<PathItem> pagedIterable = fileSystemClient.listPaths(options, null);

    java.util.Iterator<PathItem> iterator = pagedIterable.iterator();
    PathItem item = iterator.next();

    while (item != null) {
        System.out.println(item.getName());

        if (!iterator.hasNext()) {
            break;
        }
        item = iterator.next();
    }

}

Eliminar um diretório

Você pode excluir um diretório usando um dos seguintes métodos:

O exemplo de código a seguir usa deleteWithResponse para excluir um diretório não vazio e todos os caminhos abaixo do diretório:

public void DeleteDirectory(
        DataLakeFileSystemClient fileSystemClient,
        String directoryName) {

    DataLakeDirectoryClient directoryClient = fileSystemClient.getDirectoryClient(directoryName);

    // Set to true to delete all paths beneath the directory
    boolean recursive = true;

    directoryClient.deleteWithResponse(recursive, null, null, null);
}

Partilhar via