التشغيل السريع: ملحق Quarkus ل Azure Blob Storage

ابدأ باستخدام ملحق Quarkus ل Azure Blob Storage لإدارة الكائنات الثنائية كبيرة الحجم والحاويات. في هذه المقالة، يمكنك اتباع الخطوات لتجربة مثال التعليمات البرمجية للمهام الأساسية.

الوثائق المرجعية | كود | الباقة (Maven) | عينة

المتطلبات الأساسية

حساب Azure باشتراك نشط - قم بإنشاء حساب مجانا.
Azure CLI - قم بتثبيت Azure CLI 2.62.0 أو أعلى لتشغيل أوامر Azure CLI.
حساب تخزين Azure - قم بإنشاء حساب تخزين.
Java Development Kit (JDK) الإصدار 17 أو أعلى.
أباتشي مافن.

اعداد

يرشدك هذا القسم خلال إعداد مشروع للعمل مع ملحقات Quarkus ل Azure Blob Storage.

قم بتنزيل نموذج التطبيق

نموذج التطبيق المستخدم في هذا التشغيل السريع هو تطبيق Quarkus أساسي.

استخدم git لتنزيل نسخة من التطبيق إلى بيئة التطوير الخاصة بك، والانتقال إلى الدليل storage-blob-quarkus .

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

المصادقة على Azure وتخويل الوصول إلى بيانات الكائن الثنائي كبير الحجم

يجب تفويض طلبات التطبيق إلى Azure Blob Storage. يعد استخدام DefaultAzureCredential مكتبة عميل Azure Identity والأسلوب الموصى به لتنفيذ اتصالات بدون كلمة مرور بخدمات Azure في التعليمات البرمجية الخاصة بك، بما في ذلك Blob Storage. يدعم ملحق Quarkus لخدمات Azure هذا النهج.

DefaultAzureCredential هو تنفيذ سلسلة بيانات اعتماد توفره مكتبة عميل Azure Identity ل Java. DefaultAzureCredential يدعم طرق مصادقة متعددة ويحدد الطريقة التي يجب استخدامها في وقت التشغيل. يمكن هذا الأسلوب تطبيقك من استخدام طرق مصادقة مختلفة في بيئات مختلفة (محلية مقابل إنتاج) دون تنفيذ تعليمات برمجية خاصة بالبيئة.

يمكن العثور على الترتيب والمواقع التي تبحث DefaultAzureCredential فيها عن بيانات الاعتماد في نظرة عامة على مكتبة هوية Azure.

في هذا التشغيل السريع، يصادق تطبيقك باستخدام بيانات اعتماد تسجيل الدخول إلى Azure CLI عند التشغيل محليا. بعد نشره في Azure، يمكن لتطبيقك بعد ذلك استخدام هوية مدارة. لا يتطلب هذا الانتقال بين البيئات أي تغييرات في التعليمات البرمجية.

تعيين الأدوار إلى حساب مستخدم Microsoft Entra الخاص بك

عند التطوير محليا، تأكد من أن حساب المستخدم الذي يصل إلى بيانات الكائن الثنائي كبير الحجم لديه الأذونات الصحيحة. ستحتاج إلى مساهم بيانات كائن ثنائي كبير الحجم للتخزين لقراءة بيانات الكائن الثنائي كبير الحجم وكتابتها. لتعيين هذا الدور لنفسك، ستحتاج إلى تعيين دور مسؤول وصول المستخدم، أو دور آخر يتضمن إجراء Microsoft.Authorization/roleAssignments/write . يمكنك تعيين أدوار Azure RBAC لمستخدم باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell. لمزيد من المعلومات حول دور مساهم بيانات Storage Blob ، راجع مساهم بيانات Blob للتخزين. لمزيد من المعلومات حول النطاقات المتوفرة لتعيينات الأدوار، راجع فهم نطاق Azure RBAC.

في هذا السيناريو، ستقوم بتعيين أذونات لحساب المستخدم الخاص بك، في نطاق حساب التخزين، لاتباع مبدأ الامتياز الأقل. تمنح هذه الممارسة المستخدمين الحد الأدنى من الأذونات المطلوبة فقط وتنشئ بيئات تشغيل أكثر أمانًا.

سيقوم المثال التالي بتعيين دور مساهم بيانات كائن ثنائي كبير الحجم للتخزين إلى حساب المستخدم الخاص بك، والذي يوفر حق الوصول للقراءة والكتابة إلى بيانات الكائن الثنائي كبير الحجم في حساب التخزين الخاص بك.

هام

في معظم الحالات، سيستغرق نشر تعيين الدور في Azure دقيقة أو دقيقتين، ولكن في حالات نادرة قد يستغرق الأمر ما يصل إلى ثماني دقائق. إذا تلقيت أخطاء المصادقة عند تشغيل التعليمات البرمجية لأول مرة، فانتظر بضع لحظات وحاول مرة أخرى.

في مدخل Microsoft Azure، حدد موقع حساب التخزين الخاص بك باستخدام شريط البحث الرئيسي أو شريط التنقل الأيسر.
في صفحة نظرة عامة على حساب التخزين، حدد التحكم في الوصول (IAM) من القائمة اليمنى.
حدد صفحة التحكم بالوصول (IAM)، وحدد علامة تبويب تعيينات الدور.
حدد + إضافة من القائمة العلوية ثم إضافة تعيين الدور من القائمة المنسدلة الناتجة.
استخدم مربع البحث لتصفية النتائج إلى الدور المطلوب. على سبيل المثال، ابحث عن مساهم بيانات كائن ثنائي كبير الحجم للتخزين وحدد نتيجة المطابقة، ثم اختر التالي.
ضمن تعيين الوصول إلى، حدد المستخدم أو المجموعة أو كيان الخدمة، ثم اختر + تحديد الأعضاء.
في مربع الحوار، ابحث عن اسم مستخدم Microsoft Entra (عنوان بريدك الإلكتروني user@domain عادة) ثم اختر تحديد في أسفل مربع الحوار.
حدد مراجعة + تعيين للانتقال إلى الصفحة النهائية، ثم مراجعة + تعيين مرة أخرى لإكمال العملية.

لتعيين دور على مستوى المورد باستخدام Azure CLI، يجب عليك أولا استرداد معرف المورد باستخدام الأمر az storage account show . يمكنك تصفية خصائص الإخراج باستخدام المعلمة --query.

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

انسخ الإخراج Id من الأمر السابق. يمكنك بعد ذلك تعيين الأدوار باستخدام أمر az role لـ Azure CLI.

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

لتعيين دور على مستوى المورد باستخدام Azure PowerShell، يجب أولا استرداد معرف المورد باستخدام Get-AzResource الأمر .

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

انسخ القيمة Id من إخراج الأمر السابق. يمكنك بعد ذلك تعيين الأدوار باستخدام الأمر New-AzRoleAssignment في PowerShell.

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

يمكنك تفويض الوصول إلى البيانات في حساب التخزين الخاص بك باستخدام الخطوات التالية:

تأكد من مصادقتك باستخدام نفس حساب Microsoft Entra الذي قمت بتعيين الدور له في حساب التخزين الخاص بك. يوضح المثال التالي كيفية المصادقة عبر Azure CLI:
```
az login
```
تأكد من توفير نقطة النهاية لحساب Azure Blob Storage. يوضح المثال التالي كيفية تعيين نقطة النهاية باستخدام متغير QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT البيئة عبر Azure CLI. استبدل <resource-group-name><storage-account-name> أسماء مجموعة الموارد وحسابات التخزين الخاصة بك قبل تشغيل الأمر:
```
export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)
```

إشعار

عند النشر في Azure، تحتاج إلى تمكين الهوية المدارة على تطبيقك، وتكوين حساب التخزين الخاص بك للسماح لهذه الهوية المدارة بالاتصال. لمزيد من المعلومات حول تكوين هذا الاتصال بين خدمات Azure، راجع مصادقة تطبيقات Java المستضافة في Azure.

تشغيل تطبيق العرض التوضيحي

ينفذ مثال التعليمات البرمجية الإجراءات التالية:

يحقن عنصر عميل مصرح به بالفعل للوصول إلى البيانات باستخدام DefaultAzureCredential ملحق Quarkus ل Azure Blob Storage.
إنشاء حاوية في حساب تخزين.
تحميل كائن ثنائي كبير الحجم إلى الحاوية.
يسرد الكائنات الثنائية كبيرة الحجم في الحاوية.
تنزيل بيانات الكائن الثنائي كبير الحجم إلى نظام الملفات المحلي.
يحذف موارد الكائن الثنائي كبير الحجم والحاويات التي أنشأها التطبيق.
حذف المصدر المحلي والملفات التي تم تنزيلها.

قم بتشغيل التطبيق في وضع JVM باستخدام الأمر التالي:

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

يشبه إخراج التطبيق المثال التالي (تم حذف قيم UUID لسهولة القراءة):

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

قبل البدء في عملية التنظيف ، تحقق من مجلد البيانات الخاص بك بحثا عن الملفين. يمكنك مقارنتها وملاحظة أنها متطابقة.

اختياريا، يمكنك تشغيل العينة في الوضع الأصلي. للقيام بذلك ، تحتاج إلى تثبيت GraalVM ، أو استخدام صورة منشئ لإنشاء الملف القابل للتنفيذ الأصلي. لمزيد من المعلومات، راجع إنشاء ملف تنفيذي أصلي. يستخدم هذا التشغيل السريع Docker كوقت تشغيل حاوية لإنشاء ملف Linux قابل للتنفيذ أصلي. إذا لم تقم بتثبيت Docker ، فيمكنك تنزيله من موقع Docker.

قم بتشغيل الأمر التالي لإنشاء الملف القابل للتنفيذ الأصلي وتنفيذه في بيئة Linux:

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

فهم نموذج التعليمات البرمجية

بعد ذلك ، يمكنك تصفح نموذج التعليمات البرمجية لفهم كيفية عمله.

حقن كائن عميل بوصول مصرح به

يبدأ العمل مع أي مورد Azure باستخدام SDK بإنشاء عنصر عميل. يقوم ملحق Quarkus ل Azure Blob Storage تلقائيا بحقن عنصر عميل بوصول مصرح به باستخدام DefaultAzureCredential.

لحقن كائن عميل بنجاح، تحتاج أولا إلى إضافة الامتدادات quarkus-arc وإلى quarkus-azure-storage-blob ملف pom.xml الخاص بك كتبعيات:

<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 مطلوب لاستخدام التعليق التوضيحي @Inject لإدخال كائن العميل في التعليمات البرمجية للتطبيق. quarkus-bom يتم استخدام التبعيات والتبعيات quarkus-azure-services-bom لإدارة إصدارات النظام الأساسي Quarkus وملحق Quarkus لخدمات Azure.

بعد ذلك، يمكنك إدخال كائن العميل في التعليمات البرمجية للتطبيق باستخدام التعليق التوضيحي @Inject :

@Inject
BlobServiceClient blobServiceClient;

هذا كل ما تحتاجه لترميز للحصول على عنصر عميل باستخدام ملحق Quarkus ل Azure Blob Storage. للتأكد من أن كائن العميل مصرح له بالوصول إلى حساب التخزين الخاص بك في وقت التشغيل، تحتاج إلى اتباع الخطوات الواردة في القسم السابق المصادقة على Azure وتخويل الوصول إلى بيانات الكائن الثنائي كبير الحجم قبل تشغيل التطبيق.

إدارة الكائنات الثنائية كبيرة الحجم والحاويات

يوضح مثال التعليمات البرمجية التالي كيفية إنشاء حاوية، وتحميل كائن ثنائي كبير الحجم، وإدراج الكائنات الثنائية كبيرة الحجم في حاوية، وتنزيل كائن ثنائي كبير الحجم.

إشعار

تعتبر الكتابة إلى نظام الملفات المحلي ممارسة سيئة في التطبيقات السحابية الأصلية. ومع ذلك، يستخدم المثال نظام الملفات المحلي لتوضيح استخدام تخزين الكائن الثنائي كبير الحجم بطريقة يسهل على المستخدم التحقق منها. عندما تنقل تطبيقا إلى الإنتاج ، راجع خيارات التخزين الخاصة بك واختر الخيار الأفضل لاحتياجاتك. لمزيد من المعلومات، راجع مراجعة خيارات التخزين.

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

تشبه هذه العمليات العمليات تلك الموضحة في التشغيل السريع: مكتبة عميل Azure Blob Storage ل Java SE. لمزيد من تفسيرات التعليمات البرمجية التفصيلية، راجع الأقسام التالية في هذا التشغيل السريع:

تنظيف

يمكنك اختيار اتباع الارتباطات الموجودة في قسم الخطوات التالية لنشر تطبيق Quarkus إلى Azure. أو يمكنك تنظيف حساب التخزين عن طريق حذف مجموعة الموارد. لمزيد من المعلومات، راجع مجموعة موارد Azure Resource Manager وحذف الموارد.

الخطوات التالية

نماذج Azure Storage وأدلة المطورين ل Java نشر تطبيق Java باستخدام Quarkus على مجموعة خدمة Azure Kubernetes نشر تطبيق Java باستخدام Quarkus على Azure Container Apps

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-10-09