مشاركة عبر

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

  • مقالة

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

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

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

إعداد بيئتك

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

تثبيت الحزم

من دليل المشروع الخاص بك، قم بتثبيت حزم Azure Blob Storage ومكتبات عميل Azure Identity باستخدام dotnet add package الأمر . حزمة Azure.Identity مطلوبة للاتصالات بدون كلمة مرور بخدمات Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

أضف توجيهات using

أضف هذه using التوجيهات إلى أعلى ملف التعليمات البرمجية:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

قد تتطلب بعض أمثلة التعليمات البرمجية في هذه المقالة توجيهات إضافية using .

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

لتوصيل تطبيق ب Blob Storage، قم بإنشاء مثيل BlobServiceClient. يوضح المثال التالي كيفية إنشاء كائن عميل باستخدام DefaultAzureCredential للتخويل:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

يمكنك تسجيل عميل خدمة لإدخال التبعية في تطبيق .NET.

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

التصريح

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

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

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

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

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

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

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

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

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

تقوم StartCopyFromUri والأساليب StartCopyFromUriAsync بإرجاع كائن CopyFromUriOperation يحتوي على معلومات حول عملية النسخ. يتم استخدام هذه الأساليب عندما تريد جدولة غير متزامنة لعملية نسخ.

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

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

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

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

//-------------------------------------------------
// Copy a blob from a different storage account
//-------------------------------------------------
public static async Task CopyAcrossStorageAccountsAsync(
    BlobClient sourceBlob,
    BlockBlobClient destinationBlob)
{
    // Lease the source blob to prevent changes during the copy operation
    BlobLeaseClient sourceBlobLease = new(sourceBlob);

    // Create a Uri object with a SAS token appended - specify Read (r) permissions
    Uri sourceBlobSASURI = await GenerateUserDelegationSAS(sourceBlob);

    try
    {
        await sourceBlobLease.AcquireAsync(BlobLeaseClient.InfiniteLeaseDuration);

        // Start the copy operation and wait for it to complete
        CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceBlobSASURI);
        await copyOperation.WaitForCompletionAsync();
    }
    catch (RequestFailedException ex)
    {
        // Handle the exception
    }
    finally
    {
        // Release the lease once the copy operation completes
        await sourceBlobLease.ReleaseAsync();
    }
}

async static Task<Uri> GenerateUserDelegationSAS(BlobClient sourceBlob)
{
    BlobServiceClient blobServiceClient =
        sourceBlob.GetParentBlobContainerClient().GetParentBlobServiceClient();

    // Get a user delegation key for the Blob service that's valid for 1 day
    UserDelegationKey userDelegationKey =
        await blobServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                          DateTimeOffset.UtcNow.AddDays(1));

    // Create a SAS token that's also valid for 1 day
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        BlobContainerName = sourceBlob.BlobContainerName,
        BlobName = sourceBlob.Name,
        Resource = "b",
        StartsOn = DateTimeOffset.UtcNow,
        ExpiresOn = DateTimeOffset.UtcNow.AddDays(1)
    };

    // Specify read permissions for the SAS
    sasBuilder.SetPermissions(BlobSasPermissions.Read);

    // Add the SAS token to the blob URI
    BlobUriBuilder blobUriBuilder = new BlobUriBuilder(sourceBlob.Uri)
    {
        // Specify the user delegation key
        Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                              blobServiceClient.AccountName)
    };

    return blobUriBuilder.ToUri();
}

إشعار

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

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

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

//-------------------------------------------------
// Copy a blob from an external source
//-------------------------------------------------
public static async Task CopyFromExternalSourceAsync(
    string sourceLocation,
    BlockBlobClient destinationBlob)
{
    Uri sourceUri = new(sourceLocation);

    // Start the copy operation and wait for it to complete
    CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceUri);
    await copyOperation.WaitForCompletionAsync();
}

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

للتحقق من Copy Blob حالة العملية، يمكنك استدعاء UpdateStatusAsync وتحليل الاستجابة للحصول على قيمة x-ms-copy-status العنوان.

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

public static async Task CheckCopyStatusAsync(CopyFromUriOperation copyOperation)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
        Console.WriteLine($"Copy status: {value}");
}

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

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

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

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

public static async Task AbortBlobCopyAsync(
    CopyFromUriOperation copyOperation,
    BlobClient destinationBlob)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
    {
        if (value == "pending")
        {
            await destinationBlob.AbortCopyFromUriAsync(copyOperation.Id);
            Console.WriteLine($"Copy operation {copyOperation.Id} aborted");
        }
    }
}

الموارد

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

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

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

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

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

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

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