Compartilhar via

Guia Rápido: Extensão do Quarkus para Azure Blob Storage

Comece com a extensão do Quarkus para Azure Blob Storage para gerenciar blobs e contêineres. 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

Configurando

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.

Baixar o aplicativo de exemplo

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

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 a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. Usar DefaultAzureCredential e a biblioteca de clientes de Identidade do Azure é a abordagem recomendada para implementar conexões sem senha para serviços do Azure em seu código, incluindo o Armazenamento de Blobs. A extensão do Quarkus para serviços do Azure dá suporte a essa abordagem.

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

A ordem e os locais nos quais DefaultAzureCredential procura por credenciais podem ser encontrados na Azure Identity library overview.

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 poderá usar uma identidade gerenciada. Essa transição entre ambientes não requer alterações de código.

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

Ao desenvolver localmente, verifique se a conta de usuário que está acessando 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, com escopo para a 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, escolha + 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

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

  1. Verifique se você está autenticado com a mesma conta do Microsoft Entra à qual atribuiu a função em 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 ponto de extremidade da sua conta do Armazenamento de Blobs do Azure. 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:

  • Injeta um objeto de cliente que já está autorizado para acesso a dados por meio de DefaultAzureCredential usando a extensão Quarkus do Armazenamento de Blobs 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 dos 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 a GraalVM instalada ou usar uma imagem do construtor para criar o executável nativo. Para obter mais informações, consulte Como criar um executável nativo. Este início rápido usa o Docker como runtime de contêiner para criar um executável nativo do Linux. Se você ainda não instalou o Docker, poderá baixá-lo no site do Docker.

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

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

Entender 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

Trabalhar com qualquer recurso do Azure usando o SDK começa com a criação de um objeto cliente. A extensão do Quarkus para o Armazenamento de Blobs do Azure injeta automaticamente 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 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 extensão quarkus-arc é necessária para usar a anotação @Inject para injetar o objeto cliente no código do aplicativo. As dependências quarkus-bom e quarkus-azure-services-bom são usadas para gerenciar as versões da plataforma Quarkus e da extensão para o Quarkus nos serviços do Azure.

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

@Inject
BlobServiceClient blobServiceClient;

Isso é tudo 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 runtime, você precisa seguir as etapas na seção anterior Autenticar no Azure e autorizar o acesso aos 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

Gravar no sistema de arquivos local é considerada uma prática incorreta em aplicativos nativos de nuvem. No entanto, o exemplo usa o sistema de arquivos local para ilustrar o uso do armazenamento de blobs de uma maneira fácil de verificar pelo usuário. Ao levar um aplicativo para produção, examine as opções de armazenamento e escolha a melhor opção para suas necessidades. Para obter mais informações, consulte Examinar as 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 no Início Rápido: biblioteca de clientes 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 o grupo de recursos e a exclusão de recursos do Azure Resource Manager.

Próximas etapas

Exemplos de Armazenamento do Azure e guias de desenvolvedor para JavaImplantar um aplicativo Java com Quarkus em um cluster do Serviço de Kubernetes do AzureImplantar um aplicativo Java com Quarkus em Aplicativos de Contêiner do Azure

  • Last updated on