Início Rápido: biblioteca de clientes para Java SE do Armazenamento de Blobs do Azure

Observação

A opção Construir do zero guia você na criação de um projeto, instalação de pacotes, escrita de código e execução de um aplicativo básico de console. Escolha essa opção para entender como criar um aplicativo que se conecte ao Armazenamento de Blobs do Azure. Para automatizar tarefas de implantação e começar com um projeto concluído, escolha Começar com um modelo.

Observação

A opção Start with a template usa a CLI do Azure Developer para automatizar tarefas de implantação e fornece um projeto concluído. Escolha essa opção para explorar o código sem completar as tarefas de configuração. Para instruções passo a passo para construir o app, escolha Construir do zero.

Introdução à biblioteca de clientes do Armazenamento de Blobs do Azure para Java a fim de gerenciar blobs e contêineres.

Neste artigo, você vai seguir as etapas para instalar o pacote e testar o código de exemplo para tarefas básicas.

Neste artigo, você usará o Azure Developer CLI para implantar recursos do Azure e executar um aplicativo de console concluído com apenas alguns comandos.

Dica

Para aplicações Spring que utilizam recursos do Armazenamento do Azure, considere o Spring Cloud Azure. Este projeto open-source integra o Spring com os serviços do Azure. Para um exemplo de Armazenamento de Blobs, veja Upload a file to a Armazenamento do Azure Blob.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (Maven) | Exemplos

Pré-requisitos

Configurando

Esta seção explica como preparar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Java.

Criar o projeto

Crie um aplicativo Java chamado blob-quickstart.

  1. Em uma janela do console (como o PowerShell ou o Bash), use o Maven para criar um aplicativo de console com o nome blob-quickstart. Digite o comando mvn a seguir para criar um projeto "Olá, Mundo!" em Java.

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.blobs.quickstart `
    --define artifactId=blob-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Revise a saída gerada ao criar o projeto.

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.blobs.quickstart
[INFO] Parameter: groupId, Value: com.blobs.quickstart
[INFO] Parameter: artifactId, Value: blob-quickstart
[INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.056 s
[INFO] Finished at: 2019-10-23T11:09:21-07:00
[INFO] ------------------------------------------------------------------------
    ```

  3. Alterne para a pasta blob-quickstart recém-criada.

    cd blob-quickstart

  4. Dentro do diretório blob-quickstart , crie outro diretório chamado data. Essa pasta é onde os arquivos de dados do blob são criados e armazenados.

    mkdir data

Instalar os pacotes

Abra o arquivo pom.xml no editor de texto.

Adicione azure-sdk-bom para usar uma dependência da última versão da biblioteca. No snippet a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Ao usar o azure-sdk-bom, você não precisa especificar a versão de cada dependência individual. Para saber mais sobre o BOM, confira o LEIAME do BOM 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>

Em seguida, adicione os elementos de dependência a seguir ao grupo de dependências. Você precisa da dependência Azure-identity para conexões sem senha com os serviços do Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Configurar o framework de aplicativos

No diretório do projeto, siga estas etapas para criar a estrutura básica do aplicativo:

  1. Navegue até o diretório /src/main/java/com/blobs/quickstart
  2. Abra o arquivo App.java em seu editor
  3. Exclua a linha System.out.println("Hello world!");
  4. Adicione as diretivas import necessárias

O código deve ser parecido com esta estrutura:

package com.blobs.quickstart;

/**
 * Azure Blob Storage quickstart
 */
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Usando a CLI do Azure Developer, você pode criar uma conta de armazenamento e executar o código de exemplo com apenas alguns comandos. Você pode rodar o projeto no seu ambiente de desenvolvimento local ou em um DevContainer.

Inicializar o modelo do Azure Developer CLI e implantar recursos

Em um diretório vazio, siga estas etapas para inicializar o modelo azd, provisionar recursos do Azure e começar a usar o código:

  • Clone os ativos do repositório de início rápido do GitHub e inicialize o modelo localmente:

    azd init --template blob-storage-quickstart-java

    Você será solicitado a obter as seguintes informações:

    • Environment name: Azure CLI do Desenvolvedor usa esse valor como prefixo para todos os recursos Azure que cria. O nome deve ser exclusivo em todas as assinaturas Azure e ter entre 3 e 24 caracteres. O nome pode conter apenas números e letras minúsculas.

  • Entre no Azure:

    azd auth login

  • Provisione e implante os recursos no Azure:

    azd up

    Você será solicitado a obter as seguintes informações:

    • Assinatura: A assinatura do Azure usada para implantar seus recursos.
    • Localização: A região Azure para implantar seus recursos.

    A implantação pode levar alguns minutos para ser concluída. A saída do azd up comando inclui o nome da conta de armazenamento recém-criada, que você precisa mais tarde para executar o código.

Execute o código de exemplo

Neste ponto, os recursos são implantados no Azure e o código está quase pronto para ser executado. Siga estas etapas para atualizar o nome da conta de armazenamento no código e executar o exemplo de aplicativo de console:

  • Atualizar o nome da conta de armazenamento:
    1. No diretório local, navegue até o diretório blob-quickstart/src/main/java/com/blobs/quickstart.
    2. Abra o arquivo chamado App.java em seu editor. Localize o espaço reservado <storage-account-name> e substitua-o pelo nome real da conta de armazenamento criada pelo comando azd up.
    3. Salve as alterações.
  • Execute o projeto:
    1. Navegue até o diretório blob-quickstart que contém o arquivo pom.xml. Compile o projeto usando o seguinte comando mvn: 
      mvn compile
    2. Empacote o código compilado no formato distribuível:
      mvn package
    3. Execute o seguinte comando mvn para executar o aplicativo: 
      mvn exec:java
  • Observar a saída: esse aplicativo cria um arquivo de teste na pasta de dados local e o carrega em um contêiner na conta de armazenamento. Em seguida, o exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos novos e antigos.

Para saber mais sobre como o código de exemplo funciona, confira Exemplos de código.

Quando terminar de testar o código, confira a seção Limpar recursos para excluir os recursos criados pelo comando azd up.

Modelo de objeto

O Armazenamento de Blobs do Azure é otimizado para armazenar grandes quantidades de dados não estruturados. Os dados não estruturados não seguem uma definição nem um modelo de dados específico, como dados de texto ou binários. O Armazenamento de Blobs oferece três tipos de recursos:

  • A conta de armazenamento
  • Um contêiner na conta de armazenamento
  • Um blob no contêiner

O diagrama a seguir mostra a relação entre esses recursos.

Diagrama que mostra uma conta de armazenamento que contém um contêiner de blobs e um blob.

Use as seguintes classes Java para interagir com esses recursos:

  • BlobServiceClient: A BlobServiceClient classe gerencia recursos e contêineres de blob do Armazenamento do Azure. A conta de armazenamento fornece o namespace de nível superior para o serviço Blob.
  • BlobServiceClientBuilder: A BlobServiceClientBuilder classe fornece uma API fluente para configurar e criar BlobServiceClient objetos.
  • BlobContainerClient: A BlobContainerClient classe gerencia contêineres do Armazenamento do Azure e seus blobs.
  • BlobClient: A BlobClient classe gerencia blobs do Armazenamento do Azure.
  • BlobItem: a classe BlobItem representa blobs individuais retornados de uma chamada a listBlobs.

Exemplos de código

Estes exemplos de snippets de código mostram como executar as seguintes ações com a biblioteca de clientes do Armazenamento de Blobs do Azure para Java:

Importante

Adicione as dependências e diretrizes descritas em Configuração antes de usar os exemplos de código.

Observação

O modelo da CLI do Desenvolvedor do Azure inclui um arquivo com código de exemplo já instalado. Os exemplos a seguir fornecem detalhes de cada parte do código de exemplo. O modelo implementa o método de autenticação sem senha recomendado, conforme descrito na seção Autenticar-se no Azure. O método de cadeia de conexão é mostrado como uma alternativa, mas não é usado no modelo e não é recomendado para o código de produção.

Autenticar-se no Azure e autorizar o acesso a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. O uso da classe DefaultAzureCredential fornecida pela biblioteca de clientes de identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no código, incluindo o Armazenamento de Blobs.

Você também pode autorizar solicitações para o Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor as chaves de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave de conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

DefaultAzureCredential é uma classe fornecida pela biblioteca de clientes da Identidade do Azure para Java. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina qual método usar no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

Você pode encontrar a ordem e os locais onde DefaultAzureCredential procura credenciais na visão geral da biblioteca Azure Identity.

Por exemplo, seu app pode se autenticar usando suas credenciais de login do Visual Studio Code ao desenvolver localmente. Seu aplicativo pode então usar uma identidade gerenciada após a implantação no Azure. Nenhuma alteração de código é necessária para essa transição.

Atribuir funções à sua conta de usuário do Microsoft Entra

Ao desenvolver localmente, verifique se a conta de usuário que está acessando os dados de blob tem as permissões corretas. Você precisará do Colaborador de Dados do Blob de Armazenamento para ler e gravar os dados de blob. Para atribuir essa função a si mesmo, você precisará receber a atribuição da função Administrador de Acesso do Usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Para obter mais informações sobre a função Colaborador de Dados do Blob de Armazenamento, consulte Colaborador de Dados do Blob de Armazenamento. Para obter mais informações sobre os escopos disponíveis para atribuições de função, consulte Noções básicas sobre o escopo do RBAC do Azure.

Nesse cenário, você atribuirá permissões à sua conta de usuário, no escopo da conta de armazenamento, para seguir o Princípio do Privilégio Mínimo. Essa prática fornece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função de Colaborador de Dados do Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob na sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure, mas em casos raros pode levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

  1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.

    Uma captura de tela mostrando como atribuir uma função.

  5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, pesquise o Colaborador de Dados do Blob de Armazenamento e selecione o resultado correspondente e, em seguida, escolha Avançar.

  6. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  7. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente, seu endereço de email usuário@domínio) e escolha Selecionar na parte inferior do diálogo.

  8. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

Entre e conecte o código do aplicativo ao Azure usando DefaultAzureCredential

Autorize o acesso aos dados da sua conta de armazenamento seguindo estes passos:

  1. Autentique usando a mesma conta Microsoft Entra à qual você atribuiu a função de conta de armazenamento. Use a CLI do Azure, Visual Studio Code ou Azure PowerShell.

    Entre no Azure por meio da CLI do Azure usando o seguinte comando:

    az login

  2. Para usar DefaultAzureCredential, adicione a dependência azure-identity a pom.xml:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

  3. Adicione este código ao método main. Quando o código roda na sua estação de trabalho local, ele usa as credenciais de desenvolvedor da ferramenta priorizada na qual você está logado para autenticar no Azure, como a CLI do Azure ou o Visual Studio Code.

    /*
 * The default credential first checks environment variables for configuration
 * If environment configuration is incomplete, it will try managed identity
 */
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(defaultCredential)
        .buildClient();

  4. Atualize o nome da conta de armazenamento no URI do seu BlobServiceClient. Encontre o nome da conta de armazenamento na página de visão geral do portal Azure.

    Uma captura de tela mostrando como localizar o nome da conta de armazenamento.

    Observação

    Quando implantado no Azure, esse mesmo código pode ser usado para autorizar solicitações para o Armazenamento do Azure de um aplicativo em execução no Azure. No entanto, você precisa habilitar a identidade gerenciada em seu aplicativo em Azure. Em seguida, configure a conta de armazenamento para permitir que essa identidade gerenciada se conecte. Para obter instruções detalhadas sobre como configurar essa conexão entre os serviços do Azure, consulte o tutorial Autenticação de aplicativos hospedados no Azure.

Criar um contêiner

Crie um novo contêiner em sua conta de armazenamento chamando o método createBlobContainer no objeto blobServiceClient. Neste exemplo, o código acrescenta um valor GUID ao nome do contêiner para garantir que ele seja exclusivo.

Adicione este código ao final do método main:

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

Para mais informações e exemplos, veja Criar um contêiner de blob com Java.

Importante

Os nomes de contêiner devem estar em minúsculas. Para saber mais sobre como nomear contêineres e blobs, veja Nomenclatura e referência de contêineres, blobs e metadados.

Carregar blobs em um contêiner

Carregue um blob em um contêiner chamando o método uploadFromFile. O código de exemplo cria um arquivo de texto no diretório data local para carregá-lo no contêiner.

Adicione este código ao final do método main:

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

Para mais informações e exemplos, veja Carregar um blob com Java.

Listar os blobs em um contêiner

Lista os blobs no contêiner chamando o método listBlobs. Nesse caso, você adicionou apenas um blob ao container, então a operação de listagem retorna apenas esse blob.

Adicione este código ao final do método main:

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

Para mais informações e exemplos, veja Listar blobs com Java.

Baixar blobs

Baixe o blob criado anteriormente chamando o método downloadToFile. O código de exemplo adiciona um sufixo de DOWNLOAD ao nome do arquivo para que você possa ver ambos os arquivos no sistema de arquivos local.

Adicione este código ao final do método main:

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

Para mais informações e exemplos, veja Download a blob with Java.

Excluir um contêiner

O código a seguir limpa os recursos criados pelo aplicativo removendo todo o contêiner usando o método de eliminação . Ele também exclui os arquivos locais criados pelo aplicativo.

O aplicativo pausa a entrada do usuário chamando System.console().readLine() antes de excluir o blob, o contêiner e os arquivos locais. Essa pausa te dá a chance de verificar se o app criou os recursos corretamente antes de excluí-los.

Adicione este código ao final do método main:

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

Para mais informações e exemplos, veja Excluir e restaurar um contêiner de blob com Java.

Executar o código

Este aplicativo cria um arquivo de teste na pasta local e o carrega no armazenamento de blobs. Em seguida, o exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos novos e antigos.

Siga estes passos para compilar, empacotar e executar o código:

  1. Procure o diretório que contém o arquivo pom.xml e compile o projeto usando o seguinte comando mvn:
    mvn compile
  2. Empacote o código compilado no formato distribuível:
    mvn package
  3. Execute o seguinte comando mvn para executar o aplicativo: 
    mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
    Para simplificar a etapa de execução, adicione exec-maven-plugin a pom.xml e configure conforme mostrado no código a seguir: 
    <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.4.0</version>
  <configuration>
    <mainClass>com.blobs.quickstart.App</mainClass>
    <cleanupDaemonThreads>false</cleanupDaemonThreads>
  </configuration>
</plugin>
    Com essa configuração, execute o aplicativo com o seguinte comando: 
    mvn exec:java

A saída do aplicativo é semelhante ao seguinte exemplo (valores de UUID omitidos para fins de legibilidade):

Azure Blob Storage - Java quickstart sample

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Antes de iniciar o processo de limpeza, verifique se os dois arquivos estão na pasta data. Você pode compará-los e observar se eles são idênticos.

Limpar os recursos

Depois de verificar os arquivos e concluir o teste, pressione Enter para excluir os arquivos de teste junto com o contêiner que você criou na conta de armazenamento. Use também a CLI do Azure para excluir recursos.

Quando terminar o início rápido, limpe os recursos criados executando o seguinte comando:

azd down

Você recebe um prompt para confirmar a exclusão dos recursos. Insira y para confirmar.

Próxima etapa

Exemplos e guias para desenvolvedores do Armazenamento do Azure para JavaGuia de início rápido: extensão do Quarkus para o Armazenamento de Blobs do AzureUse o Spring Boot para carregar um arquivo no Armazenamento de Blobs do Azure

  • Last updated on