Rychlý průvodce: rozšíření Quarkus pro Azure blob storage

Začínáme s rozšířením Quarkus pro Azure Blob Storage pro správu objektů blob a kontejnerů V tomto článku si podle kroků vyzkoušíte ukázkový kód pro základní úlohy.

Referenční dokumentace | Zdrojový kód knihovny | Balíček (Maven) | Ukázka

Požadavky

Účet Azure s aktivním předplatným – zdarma si vytvořte účet.
Azure CLI – Nainstalujte Azure CLI 2.62.0 nebo novější a spusťte příkazy Azure CLI.
Účet azure Storage – vytvořte účet úložiště.
Java Development Kit (JDK) verze 17 nebo novější.
Apache Maven

Instalace

Tato část vás provede přípravou projektu pro práci s rozšířeními Quarkus pro Azure Blob Storage.

Stažení ukázkové aplikace

Ukázková aplikace použitá v tomto rychlém startu je základní aplikace Quarkus.

Pomocí Gitu si stáhněte kopii aplikace do vývojového prostředí a přejděte do storage-blob-quarkus adresáře.

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

Ověřování v Azure a autorizace přístupu k datům objektů blob

Žádosti aplikací do služby Azure Blob Storage musí být autorizované. Použití DefaultAzureCredential a klientská knihovna Azure Identity je doporučeným přístupem k implementaci bez hesel připojení ke službám Azure ve vašem kódu, včetně služby Blob Storage. Tento přístup podporuje rozšíření Quarkus pro služby Azure.

DefaultAzureCredential je implementace řetězu přihlašovacích údajů poskytovaná klientskou knihovnou Azure Identity pro Javu. DefaultAzureCredential podporuje více metod ověřování a určuje, kterou metodu použít za běhu. Tento přístup umožňuje vaší aplikaci používat různé metody ověřování v různých prostředích (místní a produkční) bez implementace kódu specifického pro prostředí.

Pořadí a umístění, ve kterých se DefaultAzureCredential hledají přihlašovací údaje, najdete v přehledu knihovny identit Azure.

V tomto rychlém startu se vaše aplikace ověřuje pomocí přihlašovacích údajů Azure CLI při místním spuštění. Po nasazení do Azure může vaše aplikace používat spravovanou identitu. Tento přechod mezi prostředími nevyžaduje žádné změny kódu.

Přiřazení rolí k uživatelskému účtu Microsoft Entra

Při místním vývoji se ujistěte, že uživatelský účet, který přistupuje k datům objektů blob, má správná oprávnění. K čtení a zápisu dat objektů blob budete potřebovat Přispěvatel dat objektů blob služby Storage . Abyste mohli tuto roli přiřadit sami sobě, musíte mít přiřazenou roli Správce uživatelských přístupů nebo jinou roli, která zahrnuje akci Microsoft.Authorization/roleAssignments/write . Role Azure RBAC můžete uživateli přiřadit pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu. Další informace o roli Přispěvatel dat v objektech blob služby Storage najdete v tématu Přispěvatel dat objektů blob služby Storage. Další informace o dostupných oborech pro přiřazení rolí najdete v tématu Vysvětlení oboru pro Azure RBAC.

V tomto scénáři přiřadíte oprávnění vašemu uživatelskému účtu v rozsahu účtu úložiště, abyste postupovali podle zásady nejnižších oprávnění. Tento postup poskytuje uživatelům jenom minimální potřebná oprávnění a vytváří bezpečnější produkční prostředí.

Následující příklad přiřadí roli Přispěvatel dat v objektech blob služby Storage k vašemu uživatelskému účtu, který poskytuje přístup ke čtení i zápisu k datům objektů blob v účtu úložiště.

Důležité

Ve většině případů bude trvat minutu nebo dvě, než se přiřazení role rozšíří v Azure, ale ve výjimečných případech může trvat až osm minut. Pokud při prvním spuštění kódu dojde k chybám ověřování, chvíli počkejte a zkuste to znovu.

Na webu Azure Portal vyhledejte svůj účet úložiště pomocí hlavního panelu hledání nebo levé navigace.
Na stránce přehledu účtu úložiště v nabídce vlevo vyberte Řízení přístupu (IAM ).
Na stránce Řízení přístupu (IAM) vyberte kartu Přiřazení rolí.
V horní nabídce vyberte + Přidat a potom přidejte přiřazení role z výsledné rozevírací nabídky.
Pomocí vyhledávacího pole vyfiltrujte výsledky podle požadované role. V tomto příkladu vyhledejte Přispěvatel dat objektů blob služby Storage a vyberte odpovídající výsledek a pak zvolte Další.
V části Přiřadit přístup vyberte Uživatel, skupina nebo instanční objekt a pak zvolte + Vybrat členy.
V dialogovém okně vyhledejte své uživatelské jméno Microsoft Entra (obvykle vaše user@domain e-mailová adresa) a pak v dolní části dialogového okna zvolte Vybrat .
Vyberte Zkontrolovat a přiřadit přejděte na poslední stránku a pak proces dokončete opětovnou kontrolou a přiřazením .

Pokud chcete přiřadit roli na úrovni prostředku pomocí Azure CLI, musíte nejprve pomocí příkazu načíst ID az storage account show prostředku. Výstupní vlastnosti můžete filtrovat pomocí parametru --query .

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

Zkopírujte výstup Id z předchozího příkazu. Role pak můžete přiřadit příkazem az role v Azure CLI.

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

Pokud chcete přiřadit roli na úrovni prostředku pomocí Azure PowerShellu, musíte nejprve pomocí příkazu načíst ID Get-AzResource prostředku.

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

Id Zkopírujte hodnotu z předchozího výstupu příkazu. Role pak můžete přiřadit pomocí příkazu New-AzRoleAssignment v PowerShellu.

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

Přístup k datům v účtu úložiště můžete autorizovat pomocí následujícího postupu:

Ujistěte se, že jste ověřeni pomocí stejného účtu Microsoft Entra, ke kterému jste přiřadili roli k účtu úložiště. Následující příklad ukazuje, jak provést ověření pomocí Azure CLI:
```
az login
```
Ujistěte se, že jste zadali koncový bod účtu služby Azure Blob Storage. Následující příklad ukazuje, jak nastavit koncový bod pomocí proměnné QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT prostředí prostřednictvím Azure CLI. Před spuštěním příkazu nahraďte <resource-group-name> a <storage-account-name> nahraďte názvy skupin prostředků a účtů úložiště:
```
export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)
```

Poznámka:

Při nasazení do Azure musíte ve své aplikaci povolit spravovanou identitu a nakonfigurovat účet úložiště tak, aby se mohla tato spravovaná identita připojit. Další informace o konfiguraci tohoto připojení mezi službami Azure najdete v tématu Ověřování aplikací Java hostovaných v Azure.

Spusťte ukázku

Příklad kódu provádí následující akce:

Vloží objekt klienta, který je již autorizovaný pro přístup k datům pomocí DefaultAzureCredential rozšíření Quarkus pro Azure Blob Storage.
Vytvoří kontejner v účtu úložiště.
Nahraje blob do kontejneru.
Zobrazí seznam objektů blob v kontejneru.
Stáhne data objektu blob do místního systému souborů.
Odstraní obsah objektů blob a kontejnerů vytvořený aplikací.
Odstraní místní zdroj a stažené soubory.

Spusťte aplikaci v režimu JVM pomocí následujícího příkazu:

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

Výstup aplikace je podobný následujícímu příkladu (hodnoty UUID vynechané pro čitelnost):

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

Než začnete s procesem čištění, zkontrolujte, jestli složka dat obsahuje dva soubory. Můžete je porovnat a sledovat, že jsou identické.

Volitelně můžete ukázku spustit v nativním režimu. K tomu musíte mít nainstalovaný GraalVM nebo použít image tvůrce k sestavení nativního spustitelného souboru. Další informace naleznete v tématu Sestavení nativního spustitelného souboru. V tomto rychlém průvodci se k vytvoření nativního linuxového spustitelného souboru používá Docker jako container runtime. Pokud jste Docker nenainstalovali, můžete si ho stáhnout z webu Dockeru.

Spuštěním následujícího příkazu sestavte a spusťte nativní spustitelný soubor v linuxovém prostředí:

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

Vysvětlení vzorového kódu

Dále si projdete vzorový kód, abyste pochopili, jak funguje.

Vložení klientského objektu s autorizovaným přístupem

Práce s libovolným prostředkem Azure pomocí sady SDK začíná vytvořením objektu klienta. Rozšíření Quarkus pro Azure Blob Storage automaticky vloží objekt klienta s autorizovaným přístupem pomocí DefaultAzureCredential.

Pokud chcete úspěšně vložit objekt klienta, musíte nejprve přidat rozšíření quarkus-arc a quarkus-azure-storage-blob do souboru pom.xml jako závislosti.

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

Je vyžadováno rozšíření quarkus-arc, aby mohla být použita anotace @Inject k vložení klientského objektu do kódu vaší aplikace. quarkus-bom a quarkus-azure-services-bom závislosti se používají ke správě verzí platformy Quarkus a rozšíření Quarkus pro Azure služby.

Dále můžete klientský objekt vložit do kódu aplikace pomocí poznámky @Inject :

@Inject
BlobServiceClient blobServiceClient;

To je vše, co potřebujete k získání klientského objektu pomocí rozšíření Quarkus pro Azure Blob Storage. Abyste měli jistotu, že má klientský objekt oprávnění pro přístup k vašemu účtu úložiště za běhu, musíte před spuštěním aplikace postupovat podle kroků v předchozí části Ověření v Azure a autorizovat přístup k datům objektů blob .

Správa blobů a kontejnerů

Následující příklad kódu ukazuje, jak vytvořit kontejner, nahrát objekt blob, vypsat objekty blob v kontejneru a stáhnout objekt blob.

Poznámka:

Zápis do místního systému souborů se považuje za chybný postup v nativních cloudových aplikacích. Příklad však používá místní systém souborů k ilustraci použití blob storage způsobem, který uživatel může snadno ověřit. Při přechádku aplikace do produkčního prostředí zkontrolujte možnosti úložiště a zvolte nejlepší možnost pro vaše potřeby. Další informace najdete v tématu Kontrola možností úložiště.

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

Tyto operace se podobají operacím popsaným v rychlém startu: klientská knihovna Azure Blob Storage pro Javu SE. Podrobnější vysvětlení kódu najdete v následujících částech tohoto rychlého startu:

Vyčištění

Pokud chcete nasadit aplikaci Quarkus do Azure, můžete postupovat podle odkazů v části Další kroky . Nebo můžete vyčistit úložištní účet tím, že odstraníte skupinu prostředků. Další informace najdete v tématu Skupina prostředků a odstranění prostředků Azure Resource Manageru.

Další kroky

Ukázky služby Azure Storage a příručky pro vývojáře pro Nasazení aplikace v Javě pomocí Quarkus v clusteru Azure Kubernetes Service – Nasazení aplikace v Javě s Quarkus v Azure Container Apps

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-09