Snabbstart: Quarkus-tillägget för Azure Blob Storage

Kom igång med Quarkus-tillägget för Azure Blob Storage för att hantera blobar och containrar. I den här artikeln följer du stegen för att prova exempelkod för grundläggande uppgifter.

Referensdokumentation | Bibliotekens källkod | Paket (Maven) | Exempel

Förutsättningar

• Azure-konto med en aktiv prenumeration – skapa ett konto kostnadsfritt.
• Azure CLI – Installera Azure CLI 2.62.0 eller senare för att köra Azure CLI-kommandon.
• Azure Storage-konto – skapa ett lagringskonto.
• Java Development Kit (JDK) version 17 eller senare.
• Apache Maven.

Förbereda

Det här avsnittet beskriver hur du förbereder ett projekt för att arbeta med Quarkus-tilläggen för Azure Blob Storage.

Ladda ned exempelprogrammet

Exempelprogrammet som används i den här snabbstarten är ett grundläggande Quarkus-program.

Använd git för att ladda ned en kopia av programmet till utvecklingsmiljön och navigera till storage-blob-quarkus katalogen.

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

Autentisera till Azure och auktorisera åtkomst till blobdata

Programbegäranden till Azure Blob Storage måste vara auktoriserade. Användning DefaultAzureCredential och Azure Identity-klientbiblioteket är den rekommenderade metoden för att implementera lösenordslösa anslutningar till Azure-tjänster i din kod, inklusive Blob Storage. Quarkus-tillägget för Azure-tjänster stöder den här metoden.

DefaultAzureCredential är en implementering av autentiseringskedjan som tillhandahålls av Azure Identity-klientbiblioteket för Java. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning. Med den här metoden kan din app använda olika autentiseringsmetoder i olika miljöer (lokalt jämfört med produktion) utan att implementera miljöspecifik kod.

Den ordning och de platser där DefaultAzureCredential autentiseringsuppgifterna söks finns i översikten över Azure Identity Library.

I den här snabbstarten autentiserar appen med dina Inloggningsuppgifter för Azure CLI när den körs lokalt. När den har distribuerats till Azure kan din app sedan använda en hanterad identitet. Den här övergången mellan miljöer kräver inga kodändringar.

Tilldela roller till ditt Microsoft Entra-användarkonto

När du utvecklar lokalt kontrollerar du att användarkontot som har åtkomst till blobdata har rätt behörigheter. Du behöver behörigheten Storage Blob Data Contributor för att läsa och skriva blobdata. Om du vill tilldela dig själv den här rollen måste du tilldelas rollen Administratör för användaråtkomst eller en annan roll som innehåller åtgärden Microsoft.Authorization/roleAssignments/write . Du kan tilldela Azure RBAC-roller till en användare med hjälp av Azure Portal, Azure CLI eller Azure PowerShell. Mer information om rollen Storage Blob Data-deltagare finns i Storage Blob Data-deltagare. Mer information om tillgängliga omfång för rolltilldelningar finns i Förstå omfånget för Azure RBAC.

I det här scenariot tilldelar du behörigheter till ditt användarkonto, begränsat till lagringskontot, för att följa principen om lägsta behörighet. Den här metoden ger användarna endast de minsta behörigheter som krävs och skapar säkrare produktionsmiljöer.

I följande exempel tilldelas rollen Storage Blob Data Contributor till ditt användarkonto, vilket ger både läs- och skrivåtkomst till blobdata i ditt lagringskonto.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Logga in och anslut din appkod till Azure med defaultAzureCredential

Du kan auktorisera åtkomst till data i ditt lagringskonto med hjälp av följande steg:

1. Kontrollera att du är autentiserad med samma Microsoft Entra-konto som du tilldelade rollen till på ditt lagringskonto. I följande exempel visas hur du autentiserar via Azure CLI:

   az login
   

2. Se till att du anger slutpunkten för ditt Azure Blob Storage-konto. I följande exempel visas hur du anger slutpunkten med hjälp av miljövariabeln QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT via Azure CLI. Ersätt <resource-group-name> och <storage-account-name> med resursgruppens och lagringskontonamnen innan du kör kommandot:

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

Kör det här exemplet

Kodexemplet utför följande åtgärder:

• Matar in ett klientobjekt som redan har behörighet för dataåtkomst via DefaultAzureCredential hjälp av Quarkus-tillägget för Azure Blob Storage.
• Skapar en container i ett lagringskonto.
• Laddar upp en blob till containern.
• Visar en lista över blobarna i containern.
• Laddar ned blobdata till det lokala filsystemet.
• Tar bort de blob- och containerresurser som skapats av appen.
• Tar bort den lokala källan och nedladdade filer.

Kör programmet i JVM-läge med hjälp av följande kommando:

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

Utdata från appen liknar följande exempel (UUID-värden utelämnas för läsbarhet):

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

Innan du påbörjar rensningsprocessen kontrollerar du datamappen för de två filerna. Du kan jämföra dem och observera att de är identiska.

Du kan också köra exemplet i inbyggt läge. För att göra detta måste du ha GraalVM installerat eller använda en byggavbildning för att skapa den plattformsspecifika körbara filen. Mer information finns i Skapa en intern körbar fil. Den här snabbstarten använder Docker som container-runtime för att skapa en Linux-nativ körbar fil. Om du inte har installerat Docker kan du ladda ned det från Docker-webbplatsen.

Kör följande kommando för att skapa och köra den inbyggda körbara filen i en Linux-miljö:

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

Förstå exempelkoden

Därefter går du igenom exempelkoden för att förstå hur den fungerar.

Mata in ett klientobjekt med auktoriserad åtkomst

Att arbeta med en Azure-resurs med hjälp av SDK börjar med att skapa ett klientobjekt. Quarkus-tillägget för Azure Blob Storage matar automatiskt in ett klientobjekt med auktoriserad åtkomst med .DefaultAzureCredential

Om du vill mata in ett klientobjekt måste du först lägga till tilläggen quarkus-arc och quarkus-azure-storage-blob till dinpom.xml fil som beroenden:

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

Tillägget quarkus-arc krävs för att använda kommentaren @Inject för att mata in klientobjektet i programkoden. Beroendena quarkus-bom och quarkus-azure-services-bom används för att hantera versionerna av Quarkus-plattformen och Quarkus-tillägget för Azure-tjänster.

Sedan kan du mata in klientobjektet i programkoden med hjälp av kommentaren @Inject :

@Inject
BlobServiceClient blobServiceClient;

Det är allt du behöver koda för att hämta ett klientobjekt med hjälp av Quarkus-tillägget för Azure Blob Storage. För att säkerställa att klientobjektet har behörighet att komma åt ditt lagringskonto vid körning måste du följa stegen i föregående avsnitt Autentisera till Azure och auktorisera åtkomst till blobdata innan du kör programmet.

Hantera blobar och containrar

Följande kodexempel visar hur du skapar en container, laddar upp en blob, listar blobar i en container och laddar ned en blob.

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

Dessa åtgärder liknar de som beskrivs i Snabbstart: Azure Blob Storage-klientbibliotek för Java SE. Mer detaljerade kodförklaringar finns i följande avsnitt i den snabbstarten:

• Skapa en container
• Ladda upp blobar till en container
• Visa en lista över blobarna i en container
• Ladda ned blobar
• Ta bort en container

Städa upp

Du kan välja att följa länkarna i avsnittet Nästa steg för att distribuera Quarkus-programmet till Azure. Du kan också rensa lagringskontot genom att ta bort resursgruppen. Mer information finns i Resursgrupp och resursborttagning i Azure Resource Manager.

Nästa steg