Megosztás a következőn keresztül:

Rövid útmutató: Quarkus-bővítmény az Azure Blob Storage-hoz

Ismerkedés az Azure Blob Storage Quarkus bővítményével a blobok és tárolók kezeléséhez. Ebben a cikkben lépéseket követve kipróbálhatja az alapfeladatok példakódját.

Referenciadokumentáció | Kódtár forráskódja | Csomag (Maven) | Minta

Előfeltételek

Előkészítés

Ez a szakasz végigvezeti egy projekt előkészítésén az Azure Blob Storage Quarkus-bővítményeivel való munkához.

A mintaalkalmazás letöltése

A rövid útmutatóban használt mintaalkalmazás egy alapszintű Quarkus-alkalmazás.

A git használatával töltse le az alkalmazás egy példányát a fejlesztői környezetbe, és keresse meg a storage-blob-quarkus könyvtárat.

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

Hitelesítés az Azure-ban és a blobadatokhoz való hozzáférés engedélyezése

Az Azure Blob Storage-ba irányuló alkalmazáskéréseket engedélyezni kell. Az Azure Identity-ügyfélkódtár használata DefaultAzureCredential és az Azure Identity-ügyfélkódtár használata ajánlott módszer az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatok implementálásához a kódban, beleértve a Blob Storage-t is. Az Azure-szolgáltatásokHoz készült Quarkus-bővítmény támogatja ezt a megközelítést.

DefaultAzureCredential Egy hitelesítőadat-lánc implementációja, amelyet a Java-hoz készült Azure Identity ügyfélkódtár biztosít. DefaultAzureCredential több hitelesítési módszert támogat, és meghatározza, hogy melyik metódust használja futásidőben. Ez a megközelítés lehetővé teszi, hogy az alkalmazás különböző hitelesítési módszereket használjon különböző környezetekben (helyi és éles környezetben) környezetspecifikus kód implementálása nélkül.

A hitelesítő adatokat kereső sorrend és helyek DefaultAzureCredential az Azure Identity-kódtár áttekintésében találhatók.

Ebben a rövid útmutatóban az alkalmazás helyi futtatáskor hitelesíti az Azure CLI bejelentkezési hitelesítő adatait. Az Azure-ban való üzembe helyezés után az alkalmazás használhat felügyelt identitást. A környezetek közötti váltáshoz nincs szükség kódmódosításra.

Szerepkörök hozzárendelése a Microsoft Entra felhasználói fiókjához

Helyi fejlesztéskor győződjön meg arról, hogy a blobadatokhoz hozzáférő felhasználói fiók rendelkezik a megfelelő engedélyekkel. A blobadatok olvasásához és írásához tárolóblobadatok közreműködője szükséges. A szerepkör hozzárendeléséhez hozzá kell rendelnie a Felhasználói hozzáférés rendszergazdája szerepkört, vagy egy másik szerepkört, amely tartalmazza a Microsoft.Authorization/roleAssignments/write műveletet. Azure RBAC-szerepköröket rendelhet egy felhasználóhoz az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával. A Storage Blob Data Közreműködő szerepkörével kapcsolatos további információkért lásd: Storage Blob Data Közreműködő. A szerepkör-hozzárendelésekhez elérhető hatókörökről további információt az Azure RBAC hatókörének ismertetése című témakörben talál.

Ebben a forgatókönyvben engedélyeket rendel hozzá a felhasználói fiókjához, amely a tárfiókra terjed ki, hogy kövesse a minimális jogosultság elvét. Ez a gyakorlat csak a minimálisan szükséges engedélyeket biztosítja a felhasználóknak, és biztonságosabbá teszi a termelési környezeteket.

Az alábbi példa a Storage Blob Data Contributor szerepkört rendeli hozzá a felhasználói fiókjához, amely olvasási és írási hozzáférést biztosít a tárfiók blobadataihoz.

Fontos

A szerepkör-hozzárendelés propagálása a legtöbb esetben egy-két percet vesz igénybe az Azure-ban, de ritkán akár nyolc percet is igénybe vehet. Ha hitelesítési hibákat kap a kód első futtatásakor, várjon néhány percet, és próbálkozzon újra.

  1. Az Azure Portalon keresse meg a tárfiókot a fő keresősávon vagy a bal oldali navigációs sávon.

  2. A tárfiók áttekintési lapján válassza a Hozzáférés-vezérlés (IAM) lehetőséget a bal oldali menüben.

  3. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelések lapot.

  4. A felső menüből válassza az + Hozzáadás lehetőséget, majd az eredményül kapott legördülő menüből a Szerepkör-hozzárendelés hozzáadása elemet.

    Képernyőkép egy szerepkör hozzárendeléséről.

  5. A keresőmezővel szűrheti az eredményeket a kívánt szerepkörre. Ebben a példában keresse meg a Storage Blob-adatszolgáltatót , és válassza ki a megfelelő eredményt, majd válassza a Tovább gombot.

  6. A Hozzáférés hozzárendelése területen válassza a Felhasználó, csoport vagy szolgáltatásnév lehetőséget, majd válassza a + Tagok kijelölése lehetőséget.

  7. A párbeszédpanelen keresse meg a Microsoft Entra-felhasználónevet (általában a user@domain e-mail-címét), majd válassza a Párbeszédpanel alján található Kiválasztás lehetőséget.

  8. Válassza a Véleményezés + hozzárendelés lehetőséget a végső oldalra lépéshez, majd a folyamat befejezéséhez ismételje meg a Véleményezés + hozzárendelés.

Jelentkezzen be, és csatlakoztassa az alkalmazáskódot az Azure-hoz a DefaultAzureCredential használatával

A tárfiókban lévő adatokhoz való hozzáférést az alábbi lépések végrehajtásával engedélyezheti:

  1. Győződjön meg arról, hogy ugyanazzal a Microsoft Entra-fiókkal van hitelesítve, amelyhez a szerepkört hozzárendelte a tárfiókban. Az alábbi példa bemutatja, hogyan hitelesíthető az Azure CLI-vel:

    az login

  2. Győződjön meg arról, hogy megadja az Azure Blob Storage-fiók végpontját. Az alábbi példa bemutatja, hogyan állíthatja be a végpontot a környezeti változó QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT használatával az Azure CLI-vel. A parancs futtatása előtt cserélje le a <resource-group-name> és a <storage-account-name> elemeket az erőforráscsoport és a tárfiók nevére.

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

Megjegyzés:

Az Azure-ban való üzembe helyezéskor engedélyeznie kell a felügyelt identitást az alkalmazásban, és konfigurálnia kell a tárfiókot, hogy lehetővé tegye a felügyelt identitás csatlakoztatását. Az Azure-szolgáltatások közötti kapcsolat konfigurálásáról további információt az Azure által üzemeltetett Java-alkalmazások hitelesítése című témakörben talál.

A minta futtatása

A példakód a következő műveleteket hajtja végre:

  • Olyan ügyfélobjektumot injektál, amely már jogosult az adathozzáféréshez DefaultAzureCredential az Azure Blob Storage Quarkus bővítményével.
  • Tárolót hoz létre egy tárfiókban.
  • Feltölt egy blobot a tárolóba.
  • Felsorolja a tárolóban lévő blobokat.
  • Letölti a blobadatokat a helyi fájlrendszerbe.
  • Törli az alkalmazás által létrehozott blob- és tárolóerőforrásokat.
  • Törli a helyi forrást és a letöltött fájlokat.

Futtassa az alkalmazást JVM módban az alábbi paranccsal:

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

Az alkalmazás kimenete hasonló az alábbi példához (az olvashatóság érdekében kihagyott UUID-értékek):

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

A törlési folyamat megkezdése előtt ellenőrizze a két fájl adatmappáját. Összehasonlíthatja őket, és megfigyelheti, hogy azonosak.

Igény szerint natív módban is futtathatja a mintát. Ehhez telepítenie kell a GraalVM-et, vagy egy szerkesztőrendszerképet kell használnia a natív végrehajtható fájl létrehozásához. További információ: Natív végrehajtható fájl létrehozása. Ez a rövid útmutató a Dockert használja tároló-futtatókörnyezetként egy natív Linux-végrehajtható fájl létrehozásához. Ha még nem telepítette a Dockert, letöltheti a Docker webhelyéről.

Futtassa a következő parancsot a natív végrehajtható fájl Linux-környezetben való létrehozásához és végrehajtásához:

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

A mintakód ismertetése

Ezután áttekinti a mintakódot, hogy megértse, hogyan működik.

Ügyfélobjektum beszúrása engedélyezett hozzáféréssel

Bármely Azure-erőforrás SDK-val való használata egy ügyfélobjektum létrehozásával kezdődik. Az Azure Blob Storage Quarkus bővítménye automatikusan engedélyezett hozzáféréssel rendelkező kliensobjektumot injektál, DefaultAzureCredential használatával.

Az ügyfélobjektum sikeres beadásához először hozzá kell adnia a bővítményeket quarkus-arc és quarkus-azure-storage-blob a pom.xml fájlhoz függőségként:

<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 kiterjesztés szükséges ahhoz, hogy a @Inject annotációval az ügyfélobjektumot be lehessen szúrni az alkalmazáskódba. A quarkus-bom és quarkus-azure-services-bom függőségek a Quarkus platform és az Azure-szolgáltatásokhoz készült Quarkus-bővítmény verzióinak kezelésére szolgálnak.

A következő lépésben az ügyfélobjektumot beszúrhatja az alkalmazáskódba a @Inject széljegyzet használatával:

@Inject
BlobServiceClient blobServiceClient;

Csak ennyit kell kódolnia ahhoz, hogy lekérjen egy ügyfélobjektumot az Azure Blob Storage Quarkus bővítményével. Annak érdekében, hogy az ügyfélobjektum jogosult legyen a tárfiók futásidőben való elérésére, az alkalmazás futtatása előtt kövesse az előző, Hitelesítés az Azure-ba című szakaszban leírt lépéseket, és engedélyezze a blobadatokhoz való hozzáférést .

Blobok és tárolók kezelése

Az alábbi példakód bemutatja, hogyan hozhat létre tárolót, tölthet fel egy blobot, listázhat blobokat egy tárolóban, és hogyan tölthet le egy blobot.

Megjegyzés:

A helyi fájlrendszerbe való írás rossz gyakorlatnak számít a natív felhőalkalmazásokban. A példa azonban a helyi fájlrendszer használatával szemlélteti a blobtároló használatát oly módon, amelyet a felhasználó könnyen ellenőrizhet. Amikor éles környezetbe visz egy alkalmazást, tekintse át a tárolási lehetőségeket, és válassza ki az igényeinek leginkább megfelelő lehetőséget. További információ: A tárolási beállítások áttekintése.

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

Ezek a műveletek hasonlóak a Java SE-hez készült Azure Blob Storage ügyfélkódtár rövid útmutatójában leírtakhoz. A kód részletesebb magyarázatát a rövid útmutató alábbi szakaszaiban találja:

Takarítás

A Quarkus-alkalmazás Azure-ban való üzembe helyezéséhez kövesse a Következő lépések szakaszban található hivatkozásokat. Vagy törölheti a tárfiókot az erőforráscsoport törlésével. További információkért tekintse meg az Azure Resource Manager erőforráscsoportját és az erőforrás törlését.

Következő lépések

Azure Storage-minták és fejlesztői útmutatókJava-alkalmazások üzembe helyezéséhez a Quarkus használatával egy Azure Kubernetes Service-fürtönJava-alkalmazás üzembe helyezése a Quarkus használatával az Azure Container Appsben

  • Last updated on