Quickstart: Quarkus-extensie voor Azure Blob Storage

Ga aan de slag met de Quarkus-extensie voor Azure Blob Storage om blobs en containers te beheren. In dit artikel volgt u de stappen om voorbeeldcode voor basistaken uit te proberen.

Referentiedocumentatie | Bibliotheek broncode | Pakket (Maven) | Voorbeeld

Vereiste voorwaarden

• Azure-account met een actief abonnement: maak gratis een account.
• Azure CLI: installeer de Azure CLI 2.62.0 of hoger om Azure CLI-opdrachten uit te voeren.
• Azure Storage-account: maak een opslagaccount.
• Java Development Kit (JDK) versie 17 of hoger.
• Apache Maven.

Installeren

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Quarkus-extensies voor Azure Blob Storage.

De voorbeeldtoepassing downloaden

De voorbeeldtoepassing die in deze quickstart wordt gebruikt, is een eenvoudige Quarkus-toepassing.

Gebruik Git om een kopie van de toepassing te downloaden naar uw ontwikkelomgeving en navigeer naar de storage-blob-quarkus map.

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

Verifiëren bij Azure en toegang tot blobgegevens autoriseren

Toepassingsaanvragen voor Azure Blob Storage moeten worden geautoriseerd. Het gebruik DefaultAzureCredential en de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van wachtwoordloze verbindingen met Azure-services in uw code, waaronder Blob Storage. De Quarkus-extensie voor Azure-services ondersteunt deze benadering.

DefaultAzureCredential is een referentieketen-implementatie die wordt geleverd door de Azure Identity-clientbibliotheek voor Java. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

De volgorde en locaties waarin DefaultAzureCredential wordt gezocht naar referenties, vindt u in het overzicht van de Azure Identity-bibliotheek.

In deze quickstart wordt uw app geverifieerd met behulp van uw Azure CLI-aanmeldingsreferenties wanneer deze lokaal wordt uitgevoerd. Nadat deze is geïmplementeerd in Azure, kan uw app vervolgens een beheerde identiteit gebruiken. Voor deze overgang tussen omgevingen zijn geen codewijzigingen vereist.

Rollen toewijzen aan uw Microsoft Entra-gebruikersaccount

Zorg er bij het lokaal ontwikkelen voor dat het gebruikersaccount dat toegang heeft tot blobgegevens over de juiste machtigingen beschikt. U hebt Inzender voor Opslagblobgegevens nodig om blobgegevens te lezen en schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Beheerder voor gebruikerstoegang of een andere rol met de actie Microsoft.Authorization/roleAssignments/write krijgen toegewezen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van Azure Portal, Azure CLI of Azure PowerShell. Raadpleeg Storage Blob Data Contributor voor meer informatie over de rol Storage Blob Data Contributor. Zie Begrijp het bereik voor Azure RBAC voor meer informatie over de beschikbare scopes voor roltoewijzingen.

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, dat is afgestemd op het opslagaccount, om het principe van minimale bevoegdheden te volgen. Deze procedure biedt gebruikers alleen de minimale machtigingen die nodig zijn en maakt veiligere productieomgevingen.

In het volgende voorbeeld wordt de rol Inzender voor opslagblobgegevens toegewezen aan uw gebruikersaccount, dat zowel lees- als schrijftoegang biedt tot blobgegevens in uw opslagaccount.

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>

Meld u aan en verbind uw app-code met Azure met behulp van DefaultAzureCredential

U kunt toegang tot gegevens in uw opslagaccount autoriseren met behulp van de volgende stappen:

1. Zorg ervoor dat u bent geverifieerd met hetzelfde Microsoft Entra-account waaraan u de rol hebt toegewezen in uw opslagaccount. In het volgende voorbeeld ziet u hoe u zich verifieert via de Azure CLI:

   az login
   

2. Zorg ervoor dat u het eindpunt van uw Azure Blob Storage-account opgeeft. In het volgende voorbeeld ziet u hoe u het eindpunt instelt met behulp van de omgevingsvariabele QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT via de Azure CLI. Vervang <resource-group-name> en <storage-account-name> met de namen van uw resourcegroep en opslagaccount voordat u het commando uitvoert:

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

Het voorbeeld uitvoeren

In het codevoorbeeld worden de volgende acties uitgevoerd:

• Hiermee injecteert u een clientobject dat al is geautoriseerd voor gegevenstoegang via DefaultAzureCredential de Quarkus-extensie voor Azure Blob Storage.
• Hiermee maakt u een container in een opslagaccount.
• Uploadt een blob naar de container.
• Geeft een lijst weer van de blobs in de container.
• Downloadt de blobgegevens naar het lokale bestandssysteem.
• Hiermee verwijdert u de blob- en containerbronnen die door de app zijn gemaakt.
• Verwijdert de lokale bron en gedownloade bestanden.

Voer de toepassing uit in de JVM-modus met behulp van de volgende opdracht:

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

De uitvoer van de app is vergelijkbaar met het volgende voorbeeld (UUID-waarden weggelaten voor leesbaarheid):

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

Voordat u begint met het opschonen, controleert u de gegevensmap voor de twee bestanden. U kunt ze vergelijken en zien dat ze identiek zijn.

U kunt het voorbeeld desgewenst uitvoeren in de systeemeigen modus. Hiervoor moet GraalVM geïnstalleerd zijn, of een builder-image gebruiken om het native uitvoerbare bestand te bouwen. Zie Een systeemeigen uitvoerbaar bestand bouwen voor meer informatie. In deze quickstart wordt Docker gebruikt als containerruntime om een systeemeigen uitvoerbaar Linux-bestand te bouwen. Als u Docker nog niet hebt geïnstalleerd, kunt u deze downloaden vanaf de Docker-website.

Voer de volgende opdracht uit om het systeemeigen uitvoerbare bestand te bouwen en uit te voeren in een Linux-omgeving:

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

Inzicht in de voorbeeldcode

Vervolgens doorloopt u de voorbeeldcode om te begrijpen hoe deze werkt.

Een clientobject injecteren met geautoriseerde toegang

Werken met een Azure-resource met behulp van de SDK begint met het maken van een clientobject. De Quarkus-extensie voor Azure Blob Storage injecteert automatisch een clientobject met geautoriseerde toegang met behulp van DefaultAzureCredential.

Om succesvol een clientobject te injecteren, moet u eerst de extensies quarkus-arc en quarkus-azure-storage-blob als afhankelijkheden toevoegen aan uw pom.xml-bestand.

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

De quarkus-arc extensie is vereist om de @Inject aantekening te gebruiken om het clientobject in uw toepassingscode te injecteren. De quarkus-bom en quarkus-azure-services-bom afhankelijkheden worden gebruikt voor het beheren van de versies van het Quarkus-platform en de Quarkus-extensie voor Azure-services.

Vervolgens kunt u het clientobject in uw toepassingscode injecteren met behulp van de @Inject aantekening:

@Inject
BlobServiceClient blobServiceClient;

Dat is alles wat u nodig hebt om een clientobject op te halen met behulp van de Quarkus-extensie voor Azure Blob Storage. Om ervoor te zorgen dat het clientobject tijdens runtime toegang heeft tot uw opslagaccount, moet u de stappen in de vorige sectie Verifiëren bij Azure volgen en toegang tot blobgegevens autoriseren voordat u de toepassing uitvoert.

Blobs en containers beheren

In het volgende codevoorbeeld ziet u hoe u een container maakt, een blob uploadt, blobs in een container weergeeft en een blob downloadt.

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

Deze bewerkingen zijn vergelijkbaar met de bewerkingen die worden beschreven in quickstart: Azure Blob Storage-clientbibliotheek voor Java SE. Zie de volgende secties in die quickstart voor meer gedetailleerde code-uitleg:

• Een container maken
• Blobs uploaden naar een container
• De blobs in een container weergeven
• Blobs downloaden
• Een container verwijderen

Schoonmaken

U kunt ervoor kiezen om de koppelingen in de sectie Volgende stappen te volgen om de Quarkus-toepassing in Azure te implementeren. U kunt het opslagaccount ook opschonen door de resourcegroep te verwijderen. Voor meer informatie, zie Azure Resource Manager-resourcegroep en resourceverwijdering.

Volgende stappen