مشاركة عبر

تنزيل كائن ثنائي كبير الحجم باستخدام Java

  • مقالة

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

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

إعداد بيئتك

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

لاستخدام أمثلة التعليمات البرمجية في هذه المقالة، اتبع هذه الخطوات لإعداد مشروعك.

إشعار

تستخدم هذه المقالة أداة بناء Maven لإنشاء التعليمات البرمجية المثال وتشغيلها. تعمل أدوات البناء الأخرى، مثل Gradle، أيضا مع Azure SDK ل Java.

تثبيت الحزم

افتح الملف pom.xml في محرر النصوص الخاص بك. قم بتثبيت الحزم عن طريق تضمين ملف BOM، أو تضمين تبعية مباشرة.

إضافة عبارات الاستيراد

أضف عبارات import التالية:

import com.azure.storage.blob.*;
import com.azure.storage.common.*;
import com.azure.storage.blob.options.BlobDownloadToFileOptions;
import com.azure.storage.blob.specialized.*;

import java.io.ByteArrayOutputStream;
import java.io.IOException;

التصريح

يجب أن يكون لآلية التخويل الأذونات اللازمة لتنفيذ عملية التنزيل. للحصول على تخويل باستخدام معرف Microsoft Entra (مستحسن)، تحتاج إلى دور Azure RBAC المضمن Storage Blob Data Reader أو أعلى. لمعرفة المزيد، راجع إرشادات التخويل للحصول على Blob (REST API).

إنشاء كائن عميل

لتوصيل تطبيق ب Blob Storage، قم بإنشاء مثيل BlobServiceClient.

يستخدم المثال التالي BlobServiceClientBuilder لإنشاء كائن BlobServiceClient باستخدام DefaultAzureCredential، ويوضح كيفية إنشاء عملاء الحاوية والكائنات الثنائية كبيرة الحجم، إذا لزم الأمر:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

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

تنزيل كائن ثنائي كبير الحجم

يمكنك استخدام أي من الطرق التالية لتنزيل كائن ثنائي كبير الحجم:

تنزيل إلى مسار ملف

يقوم المثال التالي بتنزيل كائن ثنائي كبير الحجم إلى مسار ملف محلي:

public void downloadBlobToFile(BlobClient blobClient) {
    blobClient.downloadToFile("filepath/local-file.png");
}

تنزيل إلى دفق

يقوم المثال التالي بتنزيل كائن ثنائي كبير الحجم إلى كائن OutputStream :

public void downloadBlobToStream(BlobClient blobClient) {
    try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
        blobClient.downloadStream(outputStream);
    } catch (IOException e) {
        e.printStackTrace();
    }
}

تنزيل إلى سلسلة

يفترض المثال التالي أن الكائن الثنائي كبير الحجم هو ملف نصي، وينزل الكائن الثنائي كبير الحجم إلى كائن String :

public void downloadBlobToText(BlobClient blobClient) {
    String content = blobClient.downloadContent().toString();
    System.out.printf("Blob contents: %s%n", content);
}

تنزيل من بث

يقوم المثال التالي بتنزيل كائن ثنائي كبير الحجم عن طريق فتح BlobInputStream وقراءة من الدفق:

public void readBlobFromStream(BlobClient blobClient) {
    // Opening a blob input stream allows you to read from a blob through a normal
    // stream interface

    try (BlobInputStream blobStream = blobClient.openInputStream()) {
        blobStream.read();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

تنزيل كائن ثنائي كبير الحجم للكتلة مع خيارات التكوين

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

تحديد خيارات نقل البيانات عند التنزيل

يمكنك تكوين القيم في ParallelTransferOptions لتحسين الأداء لعمليات نقل البيانات. يمكن ضبط القيم التالية للتنزيلات استنادا إلى احتياجات تطبيقك:

  • blockSize: الحد الأقصى لحجم الكتلة المطلوب نقله لكل طلب. يمكنك تعيين هذه القيمة باستخدام أسلوب setBlockSizeLong .
  • maxConcurrency: الحد الأقصى لعدد الطلبات المتوازية الصادرة في أي وقت كجزء من نقل مواز واحد. يمكنك تعيين هذه القيمة باستخدام أسلوب setMaxConcurrency .

أضف التوجيه التالي import إلى الملف لاستخدامه ParallelTransferOptions للتنزيل:

import com.azure.storage.common.*;

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

public void downloadBlobWithTransferOptions(BlobClient blobClient) {
    ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
            .setBlockSizeLong((long) (4 * 1024 * 1024)) // 4 MiB block size
            .setMaxConcurrency(2);

    BlobDownloadToFileOptions options = new BlobDownloadToFileOptions("<localFilePath>");
    options.setParallelTransferOptions(parallelTransferOptions);

    blobClient.downloadToFileWithResponse(options, null, null);
}

لمعرفة المزيد حول خيارات ضبط نقل البيانات، راجع ضبط الأداء للتحميلات والتنزيلات باستخدام Java.

الموارد

لمعرفة المزيد حول كيفية تنزيل الكائنات الثنائية كبيرة الحجم باستخدام مكتبة عميل Azure Blob Storage ل Java، راجع الموارد التالية.

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

عمليات واجهة برمجة تطبيقات REST

يحتوي Azure SDK ل Java على مكتبات تستند إلى واجهة برمجة تطبيقات AZURE REST، مما يسمح لك بالتفاعل مع عمليات REST API من خلال نماذج Java المألوفة. تستخدم أساليب مكتبة العميل لتنزيل الكائنات الثنائية كبيرة الحجم عملية REST API التالية:

موارد مكتبة العميل

المحتوى ذو الصلة

  • هذه المقالة هي جزء من دليل مطور Blob Storage ل Java. لمعرفة المزيد، راجع القائمة الكاملة لمقالات دليل المطور في إنشاء تطبيق Java الخاص بك.