مشاركة عبر

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

  • مقالة

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

تستخدم أساليب مكتبة العميل المغطاة في هذه المقالة عملية Copy Blob REST API، ويمكن استخدامها عندما تريد إجراء نسخة بجدولة غير متزامنة. بالنسبة لمعظم سيناريوهات النسخ حيث تريد نقل البيانات إلى حساب تخزين ولديك عنوان URL للكائن المصدر، راجع نسخ كائن ثنائي كبير الحجم من عنوان URL للكائن المصدر باستخدام Java.

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

إعداد بيئتك

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

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

إشعار

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

تثبيت الحزم

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

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

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

import com.azure.core.util.polling.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.*;
import com.azure.storage.blob.sas.BlobSasPermission;
import com.azure.storage.blob.sas.BlobServiceSasSignatureValues;
import com.azure.storage.blob.specialized.*;

import java.time.*;
import java.util.*;

التصريح

يجب أن يكون لآلية التخويل الأذونات اللازمة لتنفيذ عملية نسخ، أو لإجهاض نسخة معلقة. للتخويل باستخدام معرف Microsoft Entra (مستحسن)، يختلف الدور المضمن في Azure RBAC الأقل امتيازا استنادا إلى عدة عوامل. لمعرفة المزيد، راجع إرشادات التخويل ل Copy Blob (REST API) أو Abort Copy 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>");

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

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

Copy Blob يمكن أن تنتهي العملية بشكل غير متزامن ويتم تنفيذها على أساس أفضل جهد، ما يعني أن العملية غير مضمونة للبدء فورا أو إكمالها خلال إطار زمني محدد. تتم جدولة عملية النسخ في الخلفية ويتم تنفيذها لأن الخادم لديه موارد متوفرة. يمكن أن تكتمل العملية بشكل متزامن إذا حدثت النسخة داخل نفس حساب التخزين.

Copy Blob يمكن لعملية تنفيذ أي من الإجراءات التالية:

  • انسخ الكائن الثنائي كبير الحجم الخاص بالمصدر إلى كائن ثنائي كبير الحجم في الوجهة باسم مختلف. يمكن أن يكون الكائن الثنائي كبير الحجم الوجهة كائن ثنائي كبير الحجم موجود من نفس نوع الكائن الثنائي كبير الحجم (كتلة أو إلحاق أو صفحة)، أو يمكن أن يكون كائنا ثنائيا جديدا تم إنشاؤه بواسطة عملية النسخ.
  • انسخ كائن ثنائي كبير الحجم المصدر إلى كائن ثنائي كبير الحجم الوجهة بنفس الاسم، والذي يحل محل الكائن الثنائي كبير الحجم الوجهة. يزيل هذا النوع من عمليات النسخ أي كتل غير ملتزمة ويستبدل بيانات تعريف الكائن الثنائي كبير الحجم الوجهة.
  • انسخ ملف مصدر في خدمة Azure File إلى كائن ثنائي كبير الحجم في الوجهة. يمكن أن يكون الكائن الثنائي كبير الحجم في الوجهة كائنًا ثنائيًّا كبير الحجم لكتلة موجودة، أو يمكن أن يكون كائناً ثنائياً كبير الحجم لكتلة جديدة تم إنشاؤه من خلال عملية النسخ. النسخ من الملفات إلى الكائنات الثنائية كبيرة الحجم للصفحة أو الكائنات الثنائية كبيرة الحجم للإلحاق غير مدعوم.
  • انسخ لقطة فوق الكائن الثنائي كبير الحجم الأساسي الخاص بها. من خلال ترقية لقطة إلى موضع الكائن الثنائي كبير الحجم الأساسي، يمكنك استعادة إصدار سابق من كائن ثنائي كبير الحجم.
  • انسخ لقطة إلى كائن ثنائي كبير الحجم في الوجهة باسم مختلف. يكون الكائن الثنائي كبير الحجم في الوجهة الناتج عبارة عن كائن ثنائي كبير الحجم قابل للكتابة وليس لقطة.

لمعرفة المزيد حول العملية، بما في Copy Blob ذلك معلومات حول الخصائص وعلامات الفهرس وبيانات التعريف والفوترة، راجع نسخ ملاحظات Blob.

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

يقدم هذا القسم نظرة عامة على الأساليب التي توفرها مكتبة عميل Azure Storage ل Java لتنفيذ عملية نسخ بجدولة غير متزامنة.

يلتف الأسلوب التالي عملية Copy Blob REST API، ويبدأ نسخة غير متزامنة من البيانات من الكائن الثنائي كبير الحجم المصدر:

يقوم beginCopy الأسلوب بإرجاع SyncPoller لاستقصاء تقدم عملية النسخ. نوع استجابة الاستقصاء هو BlobCopyInfo. beginCopy يتم استخدام الأسلوب عندما تريد جدولة غير متزامنة لعملية نسخ.

نسخ كائن ثنائي كبير الحجم من مصدر داخل Azure

إذا كنت تقوم بنسخ كائن ثنائي كبير الحجم داخل نفس حساب التخزين، يمكن أن تكتمل العملية بشكل متزامن. يمكن التصريح بالوصول إلى الكائن الثنائي كبير الحجم المصدر عبر معرف Microsoft Entra أو توقيع وصول مشترك (SAS) أو مفتاح حساب. لعملية نسخ متزامنة تبديلية، راجع نسخ كائن ثنائي كبير الحجم من عنوان URL لكائن مصدر باستخدام Java.

إذا كان مصدر النسخ كائن ثنائي كبير الحجم في حساب تخزين مختلف، يمكن أن تكتمل العملية بشكل غير متزامن. يجب أن يكون الكائن الثنائي كبير الحجم المصدر عاما أو مخولا عبر رمز SAS المميز. يحتاج رمز SAS المميز إلى تضمين إذن القراءة ('r'). لمعرفة المزيد حول رموز SAS المميزة، راجع تفويض الوصول باستخدام توقيعات الوصول المشتركة.

يوضح المثال التالي سيناريو لنسخ كائن ثنائي كبير الحجم المصدر من حساب تخزين مختلف بجدولة غير متزامنة. في هذا المثال، نقوم بإنشاء عنوان URL للكائن الثنائي كبير الحجم المصدر مع رمز SAS لتفويض المستخدم الملحق. يوضح المثال كيفية إنشاء رمز SAS المميز باستخدام مكتبة العميل، ولكن يمكنك أيضا توفير رمز SAS الخاص بك. يوضح المثال أيضا كيفية تأجير الكائن الثنائي كبير الحجم المصدر أثناء عملية النسخ لمنع التغييرات على الكائن الثنائي كبير الحجم من عميل مختلف. تحفظ Copy Blob ETag العملية قيمة الكائن الثنائي كبير الحجم المصدر عند بدء عملية النسخ. ETag إذا تم تغيير القيمة قبل انتهاء عملية النسخ، تفشل العملية.

public void copyBlobAcrossStorageAccounts(BlobClient sourceBlob, BlockBlobClient destinationBlob) {
    // Lease the source blob during copy to prevent other clients from modifying it
    BlobLeaseClient lease = new BlobLeaseClientBuilder()
            .blobClient(sourceBlob)
            .buildClient();

    // Create a SAS token for the source blob or use an existing one
    String sasToken = generateUserDelegationSAS(
            sourceBlob.getContainerClient().getServiceClient(),
            sourceBlob);

    // Get the source blob URL and append the SAS token
    String sourceBlobSasURL = sourceBlob.getBlobUrl() + "?" + sasToken;

    try {
        // Specifying -1 creates an infinite lease
        lease.acquireLease(-1);

        // Start the copy operation and wait for it to complete
        final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
                sourceBlobSasURL,
                Duration.ofSeconds(2));
        PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
    } finally {
        // Release the lease once the copy operation completes
        lease.releaseLease();
    }
}

public String generateUserDelegationSAS(BlobServiceClient blobServiceClient, BlobClient sourceBlob) {
    // Get a user delegation key
    OffsetDateTime delegationKeyStartTime = OffsetDateTime.now();
    OffsetDateTime delegationKeyExpiryTime = OffsetDateTime.now().plusDays(1);
    UserDelegationKey key = blobServiceClient.getUserDelegationKey(
        delegationKeyStartTime,
        delegationKeyExpiryTime);

    // Create a SAS token that's valid for one day, as an example
    OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);

    // Set the Read (r) permission on the SAS token
    BlobSasPermission permission = new BlobSasPermission().setReadPermission(true);

    BlobServiceSasSignatureValues sasValues = new BlobServiceSasSignatureValues(expiryTime, permission)
            .setStartTime(OffsetDateTime.now());

    // Create a SAS token that's valid for one day
    String sasToken = sourceBlob.generateUserDelegationSas(sasValues, key);

    return sasToken;
}

إشعار

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

نسخ كائن ثنائي كبير الحجم من مصدر خارج Azure

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

public void copyFromExternalSourceAsyncScheduling(String sourceURL, BlockBlobClient destinationBlob) {
    // Start the copy operation and wait for it to complete
    final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
            sourceURL,
            Duration.ofSeconds(2));
    PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
}

التحقق من حالة عملية النسخ

للتحقق من Copy Blob حالة العملية، يمكنك استدعاء getCopyStatus على كائن BlobCopyInfo الذي تم إرجاعه بواسطة SyncPoller.

يوضح مثال التعليمات البرمجية التالي كيفية التحقق من حالة عملية النسخ:

public void checkCopyStatus(BlobCopyInfo copyInfo) {
    // Check the status of the copy operation 
    System.out.printf("Copy status", copyInfo.getCopyStatus());
}

إجهاض عملية نسخ

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

لإجهاض عملية نسخ معلقة، قم باستدعاء الأسلوب التالي:

يلتف هذا الأسلوب عملية Abort Copy Blob REST API، والتي تلغي عملية معلقة Copy Blob . يوضح مثال التعليمات البرمجية التالي كيفية إجهاض عملية معلقة Copy Blob :

public void abortCopy(BlobCopyInfo copyInfo, BlobClient destinationBlob) {
    // Check the copy status and abort if pending
    if (copyInfo.getCopyStatus() == CopyStatusType.PENDING) {
        destinationBlob.abortCopyFromUrl(copyInfo.getCopyId());
        System.out.printf("Copy operation %s has been aborted%n", copyInfo.getCopyId());
    }
}

الموارد

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

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

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

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

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

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

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