Biblioteca de clientes do Azure File Data Lake para Java – versão 12.17.1

Azure Data Lake Storage é a solução de armazenamento otimizada da Microsoft para cargas de trabalho de análise de Big Data. Uma parte fundamental do Data Lake Storage Gen2 é a adição de um namespace hierárquico para armazenamento de Blobs. O namespace hierárquico organiza objetos/arquivos em uma hierarquia de diretórios para acesso eficiente a dados.

Código-fonte | Documentação | de referência da APIDocumentação | da API RESTDocumentação do produto | Amostras

Introdução

Pré-requisitos

• JDK (Java Development Kit) com a versão 8 ou superior
• Assinatura do Azure
• Criar conta de armazenamento

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
    <version>12.17.1</version>
</dependency>

Criar uma conta de armazenamento

Para criar uma Conta de Armazenamento, você pode usar o Portal do Azure ou a CLI do Azure. Observação: para usar o data lake, sua conta deve ter o namespace hierárquico habilitado.

# Install the extension “Storage-Preview”
az extension add --name storage-preview
# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

A URL da conta de armazenamento, posteriormente identificada como <your-storage-account-url>, seria formatada da seguinte maneira http(s)://<storage-account-name>.dfs.core.windows.net

Autenticar o cliente

Para interagir com o Serviço de Armazenamento, você precisará criar uma instância da classe Cliente de Serviço. Para tornar isso possível, você precisará da cadeia de caracteres SAS da conta SAS (assinatura de acesso compartilhado) da Conta de Armazenamento. Saiba mais em Token SAS

Obter credenciais

Token SAS

a. Use o snippet da CLI do Azure abaixo para obter o token SAS da Conta de Armazenamento.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Exemplo:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Como alternativa, obtenha o Token SAS da conta no Portal do Azure.

1. Vá para sua conta de armazenamento
2. Selecione Shared access signature no menu à esquerda
3. Clique em Generate SAS and connection string (após a instalação)

Credencial de chave compartilhada

a. Use o Nome da conta e a chave da conta. O nome da conta é o nome da conta de armazenamento.

1. Vá para sua conta de armazenamento
2. Selecione Access keys no menu à esquerda
3. Em key1/key2 Copiar o conteúdo do Key campo

ou

b. Use o cadeia de conexão.

1. Vá para sua conta de armazenamento
2. Selecione Access keys no menu à esquerda
3. Em key1/key2 Copiar o conteúdo do Connection string campo

Principais conceitos

O DataLake Storage Gen2 foi projetado para:

• Serviço vários petabytes de informações enquanto sustenta centenas de gigabits de taxa de transferência
• Permitir que você gerencie facilmente grandes quantidades de dados

Os principais recursos do DataLake Storage Gen2 incluem:

• Acesso compatível com Hadoop
• Um superconjunto de permissões POSIX
• Econômico em termos de capacidade de armazenamento de baixo custo e transações
• Driver otimizado para análise de Big Data

Uma parte fundamental do Data Lake Storage Gen2 é a adição de um namespace hierárquico para armazenamento de Blobs. O namespace hierárquico organiza objetos/arquivos em uma hierarquia de diretórios para acesso eficiente a dados.

No passado, a análise baseada na nuvem tinha que se comprometer em áreas de desempenho, gerenciamento e segurança. O Data Lake Storage Gen2 aborda cada um desses aspectos das seguintes maneiras:

• O desempenho é otimizado porque você não precisa copiar ou transformar dados como um pré-requisito para análise. O namespace hierárquico melhora muito o desempenho das operações de gerenciamento de diretório, o que melhora o desempenho geral do trabalho.
• Gerenciamento é mais fácil porque você pode organizar e manipular arquivos por meio de diretórios e subdiretórios.
• Segurança é aplicável porque você pode definir as permissões POSIX em arquivos individuais ou diretórios.
• A efetividade de custo é possível porque o Data Lake Storage Gen2 é construído sobre o armazenamento de Blob do Azure de baixo custo . Os recursos adicionais reduzem ainda mais o custo total de propriedade para executar a análise de big data no Azure.

Data Lake Storage Gen2 oferece dois tipos de recursos:

• O _filesystem usado por meio de 'DataLakeFileSystemClient'
• O _path usado por meio de 'DataLakeFileClient' ou 'DataLakeDirectoryClient'

ADLS Gen2	Blob
Sistema de arquivos	Contêiner
Caminho (Arquivo ou Diretório)	Blob

Observação: essa biblioteca de clientes não dá suporte a contas de armazenamento desabilitadas de namespace hierárquico (HNS).

Formato de URL

Os caminhos podem ser endereçáveis usando o seguinte formato de URL: a seguinte URL trata de um arquivo:

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${myfile}

Sintaxe do URI de recurso

Para a conta de armazenamento, o URI base para operações datalake inclui apenas o nome da conta:

https://${myaccount}.dfs.core.windows.net

Para um sistema de arquivos, o URI base inclui o nome da conta e o nome do sistema de arquivos:

https://${myaccount}.dfs.core.windows.net/${myfilesystem}

Para um arquivo/diretório, o URI base inclui o nome da conta, o nome do sistema de arquivos e o nome do caminho:

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${mypath}

Observe que os URIs acima podem não conter cenários mais avançados, como nomes de domínio personalizados.

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Blob de Armazenamento do Azure, incluindo:

• Criar um DataLakeServiceClient
• Criar um DataLakeFileSystemClient
• Criar um DataLakeFileClient
• Criar um DataLakeDirectoryClient
• Criar um sistema de arquivos
• Enumerar caminhos
• Renomear um arquivo
• Renomear um diretório
• Obter propriedades de arquivo
• Obter propriedades do diretório
• Autenticar com a Identidade do Azure

Criar um DataLakeServiceClient

Crie um DataLakeServiceClient usando o sasToken gerado acima.

DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

Criar um DataLakeFileSystemClient

Crie um DataLakeFileSystemClient usando um DataLakeServiceClient.

DataLakeFileSystemClient dataLakeFileSystemClient = dataLakeServiceClient.getFileSystemClient("myfilesystem");

ou

Crie um DataLakeFileSystemClient do construtor sasToken gerado acima.

DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .buildClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "?" + "<your-sasToken>")
    .buildClient();

Criar um DataLakeFileClient

Crie um DataLakeFileClient usando um DataLakeFileSystemClient.

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");

ou

Crie um FileClient do construtor sasToken gerado acima.

DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("myfile")
    .buildFileClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "myfile" + "?" + "<your-sasToken>")
    .buildFileClient();

Criar um DataLakeDirectoryClient

Obtenha um DataLakeDirectoryClient usando um DataLakeFileSystemClient.

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");

ou

Crie um DirectoryClient do construtor sasToken gerado acima.

DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("mydir")
    .buildDirectoryClient();

ou

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "mydir" + "?" + "<your-sasToken>")
    .buildDirectoryClient();

Criar um sistema de arquivos

Crie um sistema de arquivos usando um DataLakeServiceClient.

dataLakeServiceClient.createFileSystem("myfilesystem");

ou

Crie um sistema de arquivos usando um DataLakeFileSystemClient.

dataLakeFileSystemClient.create();

Enumerar caminhos

Enumerando todos os caminhos usando um DataLakeFileSystemClient.

for (PathItem pathItem : dataLakeFileSystemClient.listPaths()) {
    System.out.println("This is the path name: " + pathItem.getName());
}

Renomear um arquivo

Renomeie um arquivo usando um DataLakeFileClient.

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
fileClient.rename("new-file-system-name", "new-file-name");

Renomear um diretório

Renomeie um diretório usando um DataLakeDirectoryClient.

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
directoryClient.rename("new-file-system-name", "new-directory-name");

Obter propriedades do arquivo

Obter propriedades de um arquivo usando um DataLakeFileClient.

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
PathProperties properties = fileClient.getProperties();

Obter propriedades de diretório

Obter propriedades de um diretório usando um DataLakeDirectoryClient.

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
PathProperties properties = directoryClient.getProperties();

Autenticar com a Identidade do Azure

A biblioteca de Identidade do Azure fornece suporte ao Azure Active Directory para autenticação com o Armazenamento do Azure.

DataLakeServiceClient storageClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Solução de problemas

Ao interagir com o data lake usando essa biblioteca de clientes Java, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações da API REST. Por exemplo, se você tentar recuperar um sistema de arquivos ou caminho que não existe em sua Conta de Armazenamento, um 404 erro será retornado, indicando Not Found.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

Vários exemplos do SDK do Java datalake de armazenamento estão disponíveis para você no repositório GitHub do SDK.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.