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

Nota

A opção Construir do zero guia-o na criação de um projeto, instalação de pacotes, escrita de código e execução de uma aplicação básica de consola. Escolha esta opção para entender como criar uma aplicação que se ligue ao Armazenamento de Blobs do Azure. Para automatizar tarefas de implementação e começar com um projeto concluído, escolha Começar com um modelo.

Nota

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

Comece a utilizar a biblioteca cliente do Armazenamento de Blobs do Azure para Java para gerir blobs e contentores.

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

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 Carregar um ficheiro para um Armazenamento do Azure Blob.

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

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. Reveja o resultado da criação do 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. Esta pasta é onde os ficheiros de dados do blob são criados e armazenados.

    mkdir data

Instalar os pacotes

Abra o ficheiro pom.xml no seu editor de 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. Ao usar azure-sdk-bom, não é necessário especificar a versão de cada dependência. Para saber mais sobre o BOM, consulte o README da 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 seguintes elementos de dependência ao grupo de dependências. Precisas da dependência Azure-identity para ligações sem palavra-passe aos 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

A partir do diretório do projeto, siga estes passos para criar a estrutura básica da aplicação:

  1. Navegue para 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. Adicionar 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
    }
}

Ao usar a CLI do Azure Developer, pode criar uma conta de armazenamento e executar o código de exemplo com apenas alguns comandos. Pode executar o projeto no seu ambiente de desenvolvimento local ou num 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

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

    • Nome do ambiente: Azure CLI de Desenvolvedor usa este valor como prefixo para todos os recursos Azure que cria. O nome deve ser único em todas as subscrições do Azure e ter entre 3 e 24 caracteres. O nome pode conter apenas letras minúsculas e números.

  • Iniciar sessão no Azure:

    azd auth login

  • Provisione e implante os recursos no Azure:

    azd up

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

    • Subscrição: A subscrição do Azure para implementar os seus recursos.
    • Localização: A região do Azure para implementar os 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 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 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 comando azd up.
    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 que mostra uma conta de armazenamento que contém um contentor de blobs e um blob.

Use as seguintes classes Java para interagir com esses recursos:

  • BlobServiceClient: A BlobServiceClient classe gere recursos e contentores 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 gere os contentores do Armazenamento do Azure e os seus blobs.
  • BlobClient: A BlobClient classe gere blobs do 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

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

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 usar 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.

Pode encontrar a ordem e os locais em que DefaultAzureCredential procura as credenciais na visão geral da biblioteca Azure Identity.

Por exemplo, a sua aplicação pode autenticar-se usando as credenciais de início de sessão do Visual Studio Code ao desenvolver localmente. A sua aplicação pode então usar uma identidade gerida após a implementação 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 esta função a si próprio, terá de receber a função de Administrador de Acesso do Utilizador 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. Para obter mais informações sobre a função Colaborador de Dados de Blob de Armazenamento, consulte Colaborador de Dados de Blob de Armazenamento. Para obter mais informações sobre os escopos disponíveis para atribuições de função, consulte Entender o escopo do Azure RBAC.

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 Storage Blob Data Contributor à sua conta de utilizador, 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 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 Controlo de Acesso (IAM), selecione o separador Atribuições de funções.

  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.

Inicie sessão e ligue o código da sua aplicação ao Azure usando o DefaultAzureCredential

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

  1. Autentique usando a mesma conta Microsoft Entra a que atribuiu o papel de conta de armazenamento. Use o 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 main método. Quando o código corre na sua estação de trabalho local, utiliza as credenciais de programador da ferramenta prioritária em que está ligado para autenticar no Azure, como o 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 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, precisa de ativar a identidade gerida na sua aplicação 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 mais informações e exemplos, veja Criar um contentor 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 mais informações e exemplos, veja Carregar um blob com Java.

Listar os blobs num recipiente

Liste os blobs no contêiner chamando o método listBlobs . Neste caso, adicionaste apenas um blob ao contentor, por isso a operação de listagem devolve 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 mais informações e exemplos, veja 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 ficheiro para que possas ver ambos os ficheiros no sistema de ficheiros 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 mais informações e exemplos, veja Descarregar um blob com Java.

Eliminar um contentor

O código seguinte limpa os recursos que a aplicação criou ao remover todo o contentor 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 pausa dá-lhe a oportunidade de verificar se a aplicação criou corretamente os recursos antes de os apagar.

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 mais informações e exemplos, veja Eliminar e restaurar um contentor 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 estes passos 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, adicione exec-maven-plugin a pom.xml e configure-o conforme mostrado no código seguinte: 
    <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 esta configuração, execute a aplicação 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.

Limpar recursos

Depois de verificares os ficheiros e terminares os testes, carrega em Enter para apagar os ficheiros de teste juntamente com o contentor que criaste na conta de armazenamento. Você também pode usar a CLI do Azure para excluir recursos.

Quando terminares o quickstart, limpa os recursos que criaste executando o seguinte comando:

azd down

Recebes um pedido para confirmar a eliminação dos recursos. Entre y para confirmar.

Próximo passo

Exemplos e guias para programadores do Armazenamento do Azure para JavaInício rápido: extensão do Quarkus para o Armazenamento de Blobs do AzureUtilize o Spring Boot para carregar um ficheiro no Armazenamento de Blobs do Azure

  • Last updated on