Partilhar via

Guia de início rápido: biblioteca de cliente do Armazenamento de Blobs do Azure para Java

  • Artigo

Nota

A opção Construir do zero orienta você passo a passo pelo processo de criação de um novo projeto, instalação de pacotes, escrita do código e execução de um aplicativo de console básico. Essa abordagem é recomendada se você quiser entender todos os detalhes envolvidos na criação de um aplicativo que se conecta ao Armazenamento de Blobs do Azure. Se preferir automatizar as tarefas de implantação e começar com um projeto concluído, escolha Iniciar com um modelo.

Nota

A opção Iniciar com um modelo usa a CLI do Desenvolvedor do Azure para automatizar tarefas de implantação e inicia você com um projeto concluído. Essa abordagem é recomendada se você quiser explorar o código o mais rápido possível sem passar pelas tarefas de configuração. Se preferir instruções passo a passo para criar o aplicativo, escolha Construir do zero.

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

Neste artigo, siga as etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Neste artigo, você usa a CLI do Desenvolvedor do Azure para implantar recursos do Azure e executar um aplicativo de console concluído com apenas alguns comandos.

Gorjeta

Se você estiver trabalhando com recursos do Armazenamento do Azure em um aplicativo Spring, recomendamos que considere o Spring Cloud Azure como uma alternativa. O Spring Cloud Azure é um projeto de código aberto que fornece integração perfeita do Spring com os serviços do Azure. Para saber mais sobre o Spring Cloud Azure e ver um exemplo usando o Armazenamento de Blob, consulte Carregar um arquivo em um Blob de Armazenamento do Azure.

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

Pré-requisitos

Configuração

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para Java.

Criar o projeto

Crie um aplicativo Java chamado blob-quickstart.

  1. Em uma janela de console (como PowerShell ou Bash), use o Maven para criar um novo aplicativo de console com o nome blob-quickstart. Digite o seguinte comando mvn para criar um "Hello world!" Projeto 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. A saída da geração do projeto deve ser algo como isto:

    [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. Ao lado do diretório blob-quickstart , crie outro diretório chamado data. Esta pasta é onde os arquivos de dados de blob serão criados e armazenados.

    mkdir data

Instalar os pacotes

Abra o arquivo no editor de pom.xml texto.

Adicione azure-sdk-bom para depender da versão mais recente da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número da versão. Usar azure-sdk-bom evita que você precise especificar a versão de cada dependência individual. Para saber mais sobre a lista técnica, consulte o Leiame da lista técnica 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 seguintes elementos de dependência ao grupo de dependências. A dependência azure-identity é necessária 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 a estrutura do aplicativo

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

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

O código deve assemelhar-se a 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
    }
}

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

Inicializar o modelo da CLI do Azure Developer e implantar recursos

Em um diretório vazio, siga estas etapas para inicializar o azd modelo, 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

    Ser-lhe-ão solicitadas as seguintes informações:

    • Nome do ambiente: esse valor é usado como um prefixo para todos os recursos do Azure criados pela CLI do Desenvolvedor do Azure. O nome deve ser exclusivo em todas as assinaturas do Azure e deve ter entre 3 e 24 caracteres. O nome pode conter apenas letras minúsculas e números.

  • Faça logon no Azure:

    azd auth login

  • Provisione e implante os recursos no Azure:

    azd up

    Ser-lhe-ão solicitadas as seguintes informações:

    • Assinatura: a assinatura do Azure na qual seus recursos são implantados.
    • Local: a região do Azure onde seus recursos são implantados.

    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ê precisará 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 execute o aplicativo de console de exemplo:

  • Atualize 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 no editor. Localize o espaço reservado <storage-account-name> e substitua-o pelo nome real da conta de armazenamento criada pelo azd up comando.
    3. Guarde as alterações.
  • Execute o projeto:
    1. Navegue até o diretório blob-quickstart que contém o pom.xml arquivo. Compile o projeto usando o seguinte mvn comando: 
      mvn compile
    2. Empacote o código compilado em seu formato distribuível: 
      mvn package
    3. Execute o seguinte mvn comando para executar o aplicativo: 
      mvn exec:java
  • Observe a saída: Este aplicativo cria um arquivo de teste em sua pasta de dados local e o carrega em um contêiner na conta de armazenamento. O exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos antigos e novos.

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

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

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 aderem a um modelo ou definição de dados específicos, como texto ou dados binários. O armazenamento de Blob oferece três tipos de recursos:

  • A conta de armazenamento
  • Um contêiner na conta de armazenamento
  • Uma bolha no recipiente

O diagrama seguinte mostra a relação entre estes recursos.

Diagrama da arquitetura de armazenamento de Blob

Use as seguintes classes Java para interagir com esses recursos:

  • BlobServiceClient: A BlobServiceClient classe permite manipular recursos de Armazenamento do Azure e contêineres de blob. A conta de armazenamento fornece o namespace de nível superior para o serviço Blob.
  • BlobServiceClientBuilder: A BlobServiceClientBuilder classe fornece uma API de construtor fluente para ajudar na configuração e instanciação de BlobServiceClient objetos.
  • BlobContainerClient: A BlobContainerClient classe permite manipular contêineres de Armazenamento do Azure e seus blobs.
  • BlobClient: A BlobClient classe permite manipular blobs de Armazenamento do Azure.
  • BlobItem: A BlobItem classe representa blobs individuais retornados de uma chamada para listBlobs.

Exemplos de código

Estes trechos de código de exemplo mostram como executar as seguintes ações com a biblioteca de cliente do Armazenamento de Blobs do Azure para Java:

Importante

Verifique se você tem as dependências corretas no pom.xml e as diretivas necessárias para que os exemplos de código funcionem, conforme descrito na seção de configuração .

Nota

O modelo da CLI do Desenvolvedor do Azure inclui um arquivo com código de exemplo já instalado. Os exemplos a seguir fornecem detalhes para 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 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 código de produção.

Autenticar 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. Usar a DefaultAzureCredential classe fornecida pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código, incluindo o Armazenamento de Blob.

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

DefaultAzureCredential é uma classe fornecida pela biblioteca de cliente do Azure Identity para Java. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

A ordem e os locais em que DefaultAzureCredential procura credenciais podem ser encontrados na visão geral da biblioteca de Identidades do Azure.

Por exemplo, seu aplicativo pode autenticar usando suas credenciais de entrada do Visual Studio Code com ao desenvolver localmente. Seu aplicativo pode usar uma identidade gerenciada depois de implantado no Azure. Não são necessárias alterações de código para esta transição.

Atribuir funções à sua conta de utilizador do Microsoft Entra

Ao desenvolver localmente, certifique-se de que a conta de usuário que está acessando dados de blob tem as permissões corretas. Você precisará do Storage Blob Data Contributor para ler e gravar dados de blob. Para atribuir essa função a si mesmo, você precisará receber a função de Administrador de Acesso de Usuário ou outra função que inclua a ação Microsoft.Authorization/roleAssignments/write . Você pode atribuir funções do RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, com escopo para a conta de armazenamento, para seguir o Princípio do Menor Privilégio. Essa prática oferece 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 de Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob em sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para que a atribuição de função se propague no Azure, mas, em casos raros, pode levar até oito minutos. Se você receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos 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, procure por Storage Blob Data Contributor e selecione o resultado correspondente e, em seguida, escolha Next.

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

  7. Na caixa de diálogo, procure seu nome de usuário do Microsoft Entra (geralmente seu endereço de e-mail user@domain ) e escolha Selecionar na parte inferior da caixa de diálogo.

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

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

Você pode autorizar o acesso aos dados em sua conta de armazenamento usando as seguintes etapas:

  1. Certifique-se de que está autenticado com a mesma conta Microsoft Entra à qual atribuiu a função na sua conta de armazenamento. Você pode autenticar por meio da CLI do Azure, do Visual Studio Code ou do Azure PowerShell.

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

    az login

  2. Para usar DefaultAzureCredentialo , verifique se a dependência azure-identity foi adicionada empom.xml:

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

  3. Adicione este código ao Main método. Quando o código é executado em sua estação de trabalho local, ele usará as credenciais de desenvolvedor da ferramenta priorizada na qual você está conectado 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. Certifique-se de atualizar o nome da conta de armazenamento no URI do .BlobServiceClient O nome da conta de armazenamento pode ser encontrado na página de visão geral do portal do Azure.

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

    Nota

    Quando implantado no Azure, esse mesmo código pode ser usado para autorizar solicitações ao Armazenamento do Azure a partir de um aplicativo em execução no Azure. No entanto, você precisará habilitar a identidade gerenciada em seu aplicativo no Azure. Em seguida, configure sua 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 contentor

Crie um novo contêiner em sua conta de armazenamento chamando o método createBlobContainer no blobServiceClient objeto. 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 Main método:

// 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 saber mais sobre como criar um contêiner e explorar mais exemplos de código, consulte Criar um contêiner de blob com Java.

Importante

Os nomes dos contentores têm de estar em minúscula. Para obter mais informações sobre a atribuição de nomes de contentores e blobs, veja Nomenclatura e Referenciação de Contentores, Blobs e Metadados.

Carregar blobs para 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 de dados local para carregar no contêiner.

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

// 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 saber mais sobre como carregar blobs e explorar mais exemplos de código, consulte Carregar um blob com Java.

Listar os blobs num contentor

Liste os blobs no contêiner chamando o método listBlobs . Nesse caso, apenas um blob foi adicionado ao contêiner, portanto, a operação de listagem retorna apenas esse blob.

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

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

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

Para saber mais sobre como listar blobs e explorar mais exemplos de código, consulte Listar blobs com Java.

Transferir 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 Main método:

// 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 saber mais sobre como baixar blobs e explorar mais exemplos de código, consulte Baixar um blob com Java.

Eliminar um contentor

O código a seguir limpa os recursos que o aplicativo criou removendo todo o contêiner usando o método delete . Ele também exclui os arquivos locais criados pelo aplicativo.

O aplicativo pausa para entrada do usuário chamando System.console().readLine() antes de excluir o blob, o contêiner e os arquivos locais. Esta é uma boa oportunidade para verificar se os recursos foram criados corretamente, antes de serem excluídos.

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

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 saber mais sobre como excluir um contêiner e explorar mais exemplos de código, consulte Excluir e restaurar um contêiner de blob com Java.

Executar o código

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

Siga as etapas para compilar, empacotar e executar o código

  1. Navegue até o diretório que contém o pom.xml arquivo e compile o projeto usando o seguinte mvn comando: 
    mvn compile
  2. Empacote o código compilado em seu formato distribuível: 
    mvn package
  3. Execute o seguinte mvn comando 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, você pode adicionar exec-maven-plugin pom.xml e configurar como mostrado abaixo: 
    <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, você pode executar o aplicativo com o seguinte comando: 
    mvn exec:java

A saída do aplicativo é semelhante ao exemplo a seguir (valores UUID omitidos para 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 a pasta de dados para os dois arquivos. Você pode compará-los e observar que eles são idênticos.

Clean up resources (Limpar recursos)

Depois de verificar os arquivos e concluir o teste, pressione a tecla Enter para excluir os arquivos de teste junto com o contêiner criado na conta de armazenamento. Você também pode usar a CLI do Azure para excluir recursos.

Quando terminar o início rápido, você poderá limpar os recursos criados executando o seguinte comando:

azd down

Você será solicitado a confirmar a exclusão dos recursos. Entre y para confirmar.

Próximo passo

Exemplos de armazenamento do Azure e guias do desenvolvedor para Java