Aracılığıyla paylaş

Hızlı Başlangıç: Azure Blob Depolama için Quarkus uzantısı

Blobları ve kapsayıcıları yönetmek için Azure Blob Depolama için Quarkus uzantısını kullanmaya başlayın. Bu makalede, temel görevler için örnek kodu denemek için adımları izleyin.

Baz belge | Kütüphane kaynak kodu | Paket (Maven) | Örnek

Önkoşullar

Kurulum

Bu bölümde, Azure Blob Depolama için Quarkus uzantılarıyla çalışacak bir proje hazırlama işleminde size yol gösterir.

Örnek uygulamayı indirme

Bu hızlı başlangıçta kullanılan örnek uygulama temel bir Quarkus uygulamasıdır.

Git'i kullanarak uygulamanın bir kopyasını geliştirme ortamınıza indirin ve dizine storage-blob-quarkus gidin.

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

Azure'da kimlik doğrulaması ve blob verilerine erişim yetkisi verme

Azure Blob Depolama'ya yönelik uygulama istekleri yetkilendirilmelidir. Ve Azure Identity istemci kitaplığını kullanmak DefaultAzureCredential , Blob Depolama dahil olmak üzere kodunuzdaki Azure hizmetlerine parolasız bağlantılar uygulamak için önerilen yaklaşımdır. Azure hizmetleri için Quarkus uzantısı bu yaklaşımı destekler.

DefaultAzureCredential , Java için Azure Identity istemci kitaplığı tarafından sağlanan bir kimlik bilgisi zinciri uygulamasıdır. DefaultAzureCredential birden çok kimlik doğrulama yöntemini destekler ve çalışma zamanında hangi yöntemin kullanılacağını belirler. Bu yaklaşım, uygulamanızın ortama özgü kod uygulamadan farklı ortamlarda (yerel ve üretim) farklı kimlik doğrulama yöntemleri kullanmasını sağlar.

Kimlik bilgilerinin arandığı DefaultAzureCredential sıra ve konumlar Azure Kimlik kitaplığına genel bakış sayfasında bulunabilir.

Bu hızlı başlangıçta, uygulamanız yerel olarak çalışırken Azure CLI oturum açma kimlik bilgilerinizi kullanarak kimlik doğrulaması yapar. Azure'a dağıtıldıktan sonra uygulamanız yönetilen kimlik kullanabilir. Ortamlar arasındaki bu geçiş için kod değişikliği gerekmez.

Microsoft Entra kullanıcı hesabınıza rol atama

Yerel olarak geliştirme yaparken blob verilerine erişen kullanıcı hesabının doğru izinlere sahip olduğundan emin olun. Blob verilerini okumak ve yazmak için "Storage Blob Data Contributor" rolüne ihtiyacınız vardır. Kendinize bu rolü atamak için Kullanıcı Erişimi Yöneticisi rolüne veya Microsoft.Authorization/roleAssignments/write eylemini içeren başka bir role atanmalısınız. Azure portalı, Azure CLI veya Azure PowerShell'i kullanarak kullanıcıya Azure RBAC rolleri atayabilirsiniz. Depolama Blob Verisi Katkıda Bulunan rolü hakkında daha fazla bilgi için Depolama Blob Verisi Katkıda Bulunan sayfasına bakın. Rol atamaları için kullanılabilir kapsamlar hakkında daha fazla bilgi için bkz. Azure RBAC kapsamını anlama.

Bu senaryoda, En Az Ayrıcalık İlkesi'ni izlemek için depolama hesabı kapsamındaki kullanıcı hesabınıza izinler atayacaksınız. Bu uygulama kullanıcılara yalnızca gereken minimum izinleri verir ve daha güvenli üretim ortamları oluşturur.

Aşağıdaki örnek, depolama hesabınızdaki blob verilerine hem okuma hem de yazma erişimi sağlayan Depolama Blob Verileri Katkıda Bulunanı rolünü kullanıcı hesabınıza atar.

Önemli

Çoğu durumda rol atamasının Azure'a yayılması bir veya iki dakika sürer, ancak nadir durumlarda sekiz dakikaya kadar sürebilir. Kodunuzu ilk kez çalıştırdığınızda kimlik doğrulama hataları alıyorsanız, birkaç dakika bekleyin ve yeniden deneyin.

  1. Azure portalında ana arama çubuğunu veya sol gezintiyi kullanarak depolama hesabınızı bulun.

  2. Depolama hesabına genel bakış sayfasında sol taraftaki menüden Erişim denetimi (IAM) öğesini seçin.

  3. Erişim denetimi (IAM) sayfasında Rol atamaları sekmesini seçin.

  4. Üstteki menüden + ekle'yi seçin ve ardından açılan menüden Rol ataması ekle'ü seçin.

    Rol atamayı gösteren ekran görüntüsü.

  5. Sonuçları istenen role göre filtrelemek için arama kutusunu kullanın. Bu örnek için Depolama Blobu Veri Katkıda Bulunanı'nı arayın ve eşleşen sonucu seçin ve ardından İleri'yi seçin.

  6. Erişim atama altında, Kullanıcı, grup veya hizmet sorumlusu seçeneğini seçin ve ardından + Üyeleri seç seçeneğine tıklayın.

  7. İletişim kutusunda Microsoft Entra kullanıcı adınızı (genellikle user@domain e-posta adresiniz) arayın ve iletişim kutusunun alt kısmındaki Seç'i seçin.

  8. Son sayfaya gitmek için Gözden geçir + ata'yı seçin ve işlemi tamamlamak için tekrar Gözden geçir + ata'yı seçin.

DefaultAzureCredential kullanarak oturum açın ve uygulama kodunuzu Azure'a bağlayın

Aşağıdaki adımları kullanarak depolama hesabınızdaki verilere erişimi yetkileyebilirsiniz:

  1. Depolama hesabınızda rolü atadığınız Microsoft Entra hesabıyla kimliğinizin doğrulanmış olduğundan emin olun. Aşağıdaki örnekte Azure CLI aracılığıyla kimlik doğrulamasının nasıl yapılacağını gösterilmektedir:

    az login

  2. Azure Blob Depolama hesabınızın uç noktasını sağladığınızdan emin olun. Aşağıdaki örnekte, Azure CLI aracılığıyla ortam değişkenini QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT kullanarak uç noktanın nasıl ayarlanacağı gösterilmektedir. <resource-group-name> ve <storage-account-name> öğelerini kaynak grubu ve depolama hesabı adlarınızla değiştirin, ardından komutu çalıştırın.

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

Uyarı

Azure'a dağıtıldığında, uygulamanızda yönetilen kimliği etkinleştirmeniz ve depolama hesabınızı bu yönetilen kimliğin bağlanmasına izin verecek şekilde yapılandırmanız gerekir. Azure hizmetleri arasında bu bağlantıyı yapılandırma hakkında daha fazla bilgi için bkz. Azure'da barındırılan Java uygulamalarının kimliğini doğrulama.

Örneği çalıştırma

Kod örneği aşağıdaki eylemleri gerçekleştirir:

  • Quarkus uzantısını kullanarak Azure Blob Depolama için DefaultAzureCredential üzerinden veri erişimi için zaten yetkilendirilmiş bir istemci nesnesini enjekte eder.
  • Depolama hesabında bir kapsayıcı oluşturur.
  • Kapsayıcıya bir blob yükler.
  • Kapsayıcıdaki blobları listeler.
  • Blob verilerini yerel dosya sistemine indirir.
  • Uygulama tarafından oluşturulan blob ve kapsayıcı kaynaklarını siler.
  • Yerel kaynağı ve indirilen dosyaları siler.

Aşağıdaki komutu kullanarak uygulamayı JVM modunda çalıştırın:

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

Uygulamanın çıkışı aşağıdaki örneğe benzer (okunabilirlik için atlanmış UUID değerleri):

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

Temizleme işlemine başlamadan önce iki dosya için veri klasörünüzü denetleyin. Bunları karşılaştırabilir ve aynı olduklarını gözlemleyebilirsiniz.

İsteğe bağlı olarak, örneği yerel modda çalıştırabilirsiniz. Bunu yapmak için GraalVM'nin yüklü olması veya yerel yürütülebilir dosyayı oluşturmak için oluşturucu görüntüsü kullanmanız gerekir. Daha fazla bilgi için bkz. Yerel Yürütülebilir Dosya Oluşturma. Bu hızlı başlangıç kılavuzunda, Linux yerel yürütülebilir dosyası oluşturmak için kapsayıcı çalışma zamanı olarak Docker kullanılır. Docker'ı yüklemediyseniz Docker web sitesinden indirebilirsiniz.

Yerel yürütülebilir dosyayı bir Linux ortamında derlemek ve yürütmek için aşağıdaki komutu çalıştırın:

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

Örnek kodu anlama

Ardından, nasıl çalıştığını anlamak için örnek kodu gözden geçirebilirsiniz.

Yetkili erişime sahip bir istemci nesnesi ekleme

SDK kullanarak herhangi bir Azure kaynağıyla çalışma, bir istemci nesnesi oluşturmakla başlar. Azure Blob Depolama için Quarkus uzantısı, DefaultAzureCredential kullanarak yetkili erişime sahip bir istemci nesnesini otomatik olarak ekler.

bir istemci nesnesini başarıyla eklemek için önce uzantıları quarkus-arc ve quarkus-azure-storage-blobpom.xml dosyanıza bağımlılık olarak eklemeniz gerekir:

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

quarkus-arc açıklamasını kullanarak istemci nesnesini uygulama kodunuza eklemek için @Inject uzantısı gereklidir. quarkus-bom ve quarkus-azure-services-bom bağımlılıkları, Azure hizmetleri için Quarkus platformunun ve Quarkus uzantısının sürümlerini yönetmek için kullanılır.

Ardından, ek açıklamayı kullanarak istemci nesnesini uygulama kodunuz içine @Inject ekleyebilirsiniz:

@Inject
BlobServiceClient blobServiceClient;

Azure Blob Depolama için Quarkus uzantısını kullanarak bir istemci nesnesi almak için bu kadar koda ihtiyacınız vardır. İstemci nesnesinin çalışma zamanında depolama hesabınıza erişme yetkisine sahip olduğundan emin olmak için önceki Azure'da kimlik doğrulaması ve uygulamayı çalıştırmadan önce blob verilerine erişim yetkisi verme bölümündeki adımları izlemeniz gerekir.

Blobları ve kapsayıcıları yönetme

Aşağıdaki kod örneğinde kapsayıcı oluşturma, blob yükleme, kapsayıcıdaki blobları listeleme ve blob indirme işlemleri gösterilmektedir.

Uyarı

Yerel dosya sistemine yazmak, bulutta yerel uygulamalarda kötü bir uygulama olarak kabul edilir. Ancak örnek, blob depolama kullanımını kullanıcının doğrulamasını kolaylaştıracak şekilde göstermek için yerel dosya sistemini kullanır. Bir uygulamayı üretime götürürken depolama seçeneklerinizi gözden geçirin ve ihtiyaçlarınız için en iyi seçeneği belirleyin. Daha fazla bilgi için bkz. Depolama seçeneklerinizi gözden geçirme.

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

Bu işlemler , Hızlı Başlangıç: Java SE için Azure Blob Depolama istemci kitaplığında açıklanan işlemlere benzer. Daha ayrıntılı kod açıklamaları için bu hızlı başlangıçtaki aşağıdaki bölümlere bakın:

Temizleme

Quarkus uygulamasını Azure'a dağıtmak için Sonraki adımlar bölümündeki bağlantıları izlemeyi seçebilirsiniz. Veya kaynak grubunu silerek depolama hesabını temizleyebilirsiniz. Daha fazla bilgi için bkz. Azure Resource Manager kaynak grubu ve kaynak silme.

Sonraki Adımlar

Java için Azure Depolama örnekleri ve geliştirici kılavuzlarıQuarkus ile Java uygulaması Azure Kubernetes Service kümesinde dağıtmaAzure Container Apps'te Quarkus ile Java uygulaması dağıtma

  • Last updated on