Partilhar via

Guia de início rápido: extensão do Quarkus para o Armazenamento de Blobs do Azure

Comece a utilizar a extensão Quarkus para o Armazenamento de Blobs do Azure para gestionar blobs e contentores. Neste artigo, você segue as etapas para experimentar o código de exemplo para tarefas básicas.

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

Pré-requisitos

Preparação

Esta seção orienta você na preparação de um projeto para trabalhar com as extensões do Quarkus para o Armazenamento de Blobs do Azure.

Baixe o aplicativo de exemplo

O aplicativo de exemplo usado neste início rápido é um aplicativo Quarkus básico.

Use o git para baixar uma cópia do aplicativo para seu ambiente de desenvolvimento e navegue até o storage-blob-quarkus diretório.

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

Autenticar-se no Azure e autorizar o acesso aos dados de blobs

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. Usar DefaultAzureCredential e a 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. A extensão Quarkus para serviços do Azure dá suporte a essa abordagem.

DefaultAzureCredential é uma implementação de cadeia de credenciais 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.

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

Neste início rápido, seu aplicativo se autentica usando suas credenciais de entrada da CLI do Azure ao ser executado localmente. Depois de implantado no Azure, seu aplicativo pode usar uma identidade gerenciada. Essa transição entre ambientes não requer nenhuma alteração de código.

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. 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, vai atribuir permissões à sua conta de utilizador, abrangendo 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 Colaborador de Dados de Blob de Armazenamento à sua conta de utilizador, proporcionando acesso para leitura e escrita 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ção 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.

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. O exemplo a seguir mostra como autenticar por meio da CLI do Azure:

    az login

  2. Certifique-se de fornecer o endpoint da sua conta Azure Blob Storage. O exemplo a seguir mostra como definir o ponto de extremidade usando a variável QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT de ambiente por meio da CLI do Azure. Substitua <resource-group-name> e <storage-account-name> pelos nomes do grupo de recursos e da conta de armazenamento antes de executar o comando:

    export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)

Observação

Quando implantado no Azure, você precisa habilitar a identidade gerenciada em seu aplicativo e configurar sua conta de armazenamento para permitir que essa identidade gerenciada se conecte. Para obter mais informações sobre como configurar essa conexão entre os serviços do Azure, consulte Autenticar aplicativos Java hospedados no Azure.

Executar o exemplo

O exemplo de código executa as seguintes ações:

  • Insere um objeto cliente que já está autorizado para acesso a dados através de DefaultAzureCredential, utilizando a extensão Quarkus para Armazenamento de Blob do Azure.
  • Cria um contêiner em uma conta de armazenamento.
  • Carrega um blob no contêiner.
  • Lista os blobs no contêiner.
  • Baixa os dados de blob para o sistema de arquivos local.
  • Exclui os recursos de blob e contêiner criados pelo aplicativo.
  • Exclui a origem local e os arquivos baixados.

Execute o aplicativo no modo JVM usando o seguinte comando:

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

A saída do aplicativo é semelhante ao exemplo a seguir (valores UUID omitidos para legibilidade):

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.

Opcionalmente, você pode executar o exemplo no modo nativo. Para fazer isso, você precisa ter o GraalVM instalado ou usar uma imagem do construtor para criar o executável nativo. Para obter mais informações, consulte Criando um executável nativo. Este início rápido usa o Docker como runtime de container para compilar um executável nativo do Linux. Se você ainda não instalou o Docker, pode baixá-lo do site do Docker.

Execute o seguinte comando para construir e executar o executável nativo em um ambiente Linux:

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

Compreender o código de exemplo

Em seguida, você percorre o código de exemplo para entender como ele funciona.

Injetar um objeto cliente com acesso autorizado

O trabalho com qualquer recurso do Azure usando o SDK começa com a criação de um objeto cliente. A extensão Quarkus para Azure Blob Storage automaticamente injeta um objeto cliente com acesso autorizado usando DefaultAzureCredential.

Para injetar com êxito um objeto cliente, primeiro você precisa adicionar as extensões quarkus-arc e quarkus-azure-storage-blob ao seu arquivo pom.xml como dependências:

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

A quarkus-arc extensão é necessária para usar a @Inject anotação para injetar o objeto cliente no código da aplicação. As dependências quarkus-bom e quarkus-azure-services-bom são usadas para gerir as versões da plataforma Quarkus e da extensão Quarkus para os serviços Azure.

Em seguida, você pode injetar o objeto cliente no código do aplicativo usando a @Inject anotação:

@Inject
BlobServiceClient blobServiceClient;

Isso é tudo o que você precisa codificar para obter um objeto cliente usando a extensão Quarkus para o Armazenamento de Blobs do Azure. Para garantir que o objeto cliente esteja autorizado a acessar sua conta de armazenamento em tempo de execução, você precisa seguir as etapas na seção anterior Autenticar no Azure e autorizar o acesso a dados de blob antes de executar o aplicativo.

Gerenciar blobs e contêineres

O exemplo de código a seguir mostra como criar um contêiner, carregar um blob, listar blobs em um contêiner e baixar um blob.

Observação

Escrever no sistema de arquivos local é considerado uma má prática em aplicativos nativos da nuvem. No entanto, o exemplo usa o sistema de arquivos local para ilustrar o uso do armazenamento de blob de uma forma que seja fácil para o usuário verificar. Quando você leva um aplicativo para produção, revise suas opções de armazenamento e escolha a melhor opção para suas necessidades. Para obter mais informações, consulte Revisar suas opções de armazenamento.

// 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);

// 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);

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

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

// 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);

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");

Essas operações são semelhantes às descritas em Início Rápido: Biblioteca de Cliente do Armazenamento de Blobs do Azure para Java SE. Para obter explicações de código mais detalhadas, consulte as seguintes seções nesse início rápido:

Limpeza

Você pode optar por seguir os links na seção Próximas etapas para implantar o aplicativo Quarkus no Azure. Ou você pode limpar a conta de armazenamento excluindo o grupo de recursos. Para obter mais informações, consulte Grupo de recursos do Azure Resource Manager e exclusão de recursos.

Próximos passos

Exemplos de armazenamento do Azure e guias do desenvolvedor para JavaImplantar um aplicativo Java com o Quarkus em um cluster do Serviço Kubernetes do AzureImplantar um aplicativo Java com o Quarkus em aplicativos de contêiner do Azure

  • Last updated on