نقل البيانات باستخدام Data Movement library

2025-02-25

تعتبر مكتبة نقل بيانات تخزين Azure مكتبة مفتوحة المصدر عبر المنصات مصممة لتحميل وتنزيل ونسخ الكائنات الثنائية كبيرة الحجم والملفات عالية الأداء. توفر مكتبة نقل البيانات طُرقًا ملائمة غير متوفرة في مكتبة عميل تخزين Azure for .NET. تسمح لك هذه الأساليب بتعيين عدد العمليات المتوازية وتتبع تقدم النقل واستئناف النقل الذي تم إلغاؤه والمزيد.

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

إذا كنت تقوم بترحيل التعليمات البرمجية من مكتبة Microsoft.Azure.Storage.DataMovement الأقدم (الإصدار 2.X.X) إلى مكتبة Azure.Storage.DataMovement الحالية (الإصدار 12.X.X)، فشاهد دليل الترحيل.

حزمة التعليمات البرمجية | المصدر للمستندات | المرجعية لواجهة برمجة التطبيقات (NuGet) | عينات: Blobs / Files.Shares

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

اشتراك Azure - إنشاء اشتراك مجاني
حساب تخزين Azure - إنشاء حساب تخزين
أحدث .NET SDK لنظام التشغيل الخاص بك. تأكد من الحصول على SDK وليس وقت التشغيل.

إعداد بيئتك

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

تثبيت الحزم

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

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

للعمل مع مكتبة الملحقات لملفات Azure، قم بتثبيت حزمة Azure.Storage.DataMovement.Files.Shares :

dotnet add package Azure.Storage.DataMovement.Files.Shares

أضف توجيهات `using`

لتشغيل أمثلة التعليمات البرمجية في هذه المقالة، أضف التوجيهات التالية using :

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.Storage.DataMovement;
using Azure.Storage.DataMovement.Blobs;

إذا كنت تستخدم مكتبة الملحقات لملفات Azure، أضف التوجيه التالي using :

using Azure.Storage.DataMovement.Files.Shares;

التصريح

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

نبذة عن مكتبة Data Movement

تتكون مكتبة Azure Storage Data Movement من مكتبة عميل شائعة ومكتبات ملحقة لتخزين Azure Blob وملفات Azure. توفر المكتبة الشائعة الوظيفة الأساسية لنقل البيانات، بينما توفر مكتبات الملحقات وظائف خاصة ب Blob Storage وملفات Azure. لمعرفة المزيد، راجع الموارد التالية:

إنشاء كائن `TransferManager`

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

إشعار

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

توضح التعليمات البرمجية التالية كيفية إنشاء كائن TransferManager :

TransferManager transferManager = new(new TransferManagerOptions());

يمكنك اختياريا توفير مثيل TransferManagerOptions إلى الدالة الإنشائية، والتي تطبق خيارات تكوين معينة على جميع عمليات النقل التي بدأها TransferManager الكائن. تتوفر خيارات التكوين التالية:

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

إنشاء كائن `StorageResource`

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

BlobsStorageResourceProvider: استخدم هذه الفئة لإنشاء StorageResource مثيلات لحاوية كائن ثنائي كبير الحجم أو كائن ثنائي كبير الحجم للكتلة أو كائن ثنائي كبير الحجم للإلحاق أو كائن ثنائي كبير الحجم للصفحة.
ShareFilesStorageResourceProvider: استخدم هذه الفئة لإنشاء StorageResource مثيلات لملف أو دليل.
LocalFilesStorageResourceProvider: استخدم هذه الفئة لإنشاء StorageResource مثيلات لنظام ملفات محلي.

إنشاء كائن `StorageResource` ل Blob Storage

توضح التعليمات البرمجية التالية كيفية إنشاء كائن StorageResource لحاويات الكائن الثنائي كبير الحجم والكائنات الثنائية كبيرة الحجم باستخدام Uri:

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

// Get a container resource
StorageResource container = await blobsProvider.FromContainerAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container"));

// Get a block blob resource - default is block blob
StorageResource blockBlob = await blobsProvider.FromBlobAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container/sample-block-blob"),
    new BlockBlobStorageResourceOptions());

// Use a similar approach to get a page blob or append blob resource

يمكنك أيضا إنشاء كائن StorageResource باستخدام كائن عميل من Azure.Storage.Blobs.

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobContainerClient blobContainerClient = new(
    new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container"),
    tokenCredential);
StorageResource containerResource = BlobsStorageResourceProvider.FromClient(blobContainerClient);

BlockBlobClient blockBlobClient = blobContainerClient.GetBlockBlobClient("sample-block-blob");
StorageResource blockBlobResource = BlobsStorageResourceProvider.FromClient(blockBlobClient);

// Use a similar approach to get a page blob or append blob resource

بدء نقل جديد

تحتاج جميع عمليات النقل إلى تحديد مصدر ووجهة. كل من المصدر والوجهة هما النوع StorageResource، والذي يمكن أن يكون إما StorageResourceContainer أو StorageResourceItem. لنقل معين، يجب أن يكون المصدر والوجهة من نفس النوع. على سبيل المثال، إذا كان المصدر حاوية كائن ثنائي كبير الحجم، يجب أن تكون الوجهة حاوية كائن ثنائي كبير الحجم.

يمكنك بدء نقل جديد عن طريق استدعاء الأسلوب التالي:

TransferManager.StartTransferAsync

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

يمكنك اختياريا توفير مثيل TransferOptions إلى StartTransferAsync أو ResumeTransferAsync، والذي يطبق خيارات تكوين معينة على نقل معين. تتوفر خيارات التكوين التالية:

CreationMode: تكوين السلوك عندما يواجه النقل موردا موجودا بالفعل. الإعدادات الافتراضية عند FailIfExists بدء عملية نقل جديدة. عند استئناف عملية نقل، يمكن أن تختلف الإعدادات الافتراضية. بالنسبة لكافة الموارد التي تم تعدادها بنجاح عند بدء النقل، CreationMode يتم تعيينها افتراضيا إلى القيمة الأولية المستخدمة. بالنسبة لأي موارد متبقية، يتم تطبيق القيمة الافتراضية العادية.
InitialTransferSize: حجم طلب النطاق الأول بالبايت. يتم تحميل أحجام نقل مفردة أصغر من هذا الحد أو تنزيلها في طلب واحد. تستمر عمليات النقل الأكبر من هذا الحد في التنزيل أو التحميل في مجموعات من الحجم MaximumTransferChunkSize. القيمة الافتراضية هي 32 MiB. عند استئناف عملية نقل، تكون القيمة الافتراضية هي القيمة المحددة عند بدء النقل لأول مرة.
MaximumTransferChunkSize: الحد الأقصى للحجم الذي يجب استخدامه لكل مجموعة عند نقل البيانات في مجموعات. القيمة الافتراضية هي 4 MiB. عند استئناف عملية نقل، تكون القيمة الافتراضية هي القيمة المحددة عند بدء النقل لأول مرة.
ProgressHandlerOptions: اختياري. خيارات لتغيير سلوك ProgressHandler.

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

يوضح مثال التعليمات البرمجية التالي كيفية بدء نقل جديد لتحميل دليل محلي إلى حاوية كائن ثنائي كبير الحجم:

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions());

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

string localDirectoryPath = "C:/path/to/directory";
Uri blobContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: LocalFilesStorageResourceProvider.FromDirectory(localDirectoryPath),
    destinationResource: await blobsProvider.FromContainerAsync(blobContainerUri));
await transferOperation.WaitForCompletionAsync();

مثال: نسخ حاوية أو كائن ثنائي كبير الحجم

يمكنك استخدام مكتبة Data Movement للنسخ بين مثيلين StorageResource . بالنسبة لموارد الكائن الثنائي كبير الحجم، يستخدم النقل عملية Put Blob From URL ، والتي تقوم بإجراء نسخة من خادم إلى خادم.

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

Uri sourceContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/source-container");
Uri destinationContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/dest-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromContainerAsync(
        sourceContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            BlobPrefix = "source/directory/prefix"
        }),
    destinationResource: await blobsProvider.FromContainerAsync(
        destinationContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            // All source blobs are copied as a single type of destination blob
            // Defaults to block blob, if not specified
            BlobType = BlobType.Block,
            BlobPrefix = "destination/directory/prefix"
        }),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

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

Uri sourceBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/source-container/source-blob");
Uri destinationBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/dest-container/dest-blob");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromBlobAsync(sourceBlobUri),
    destinationResource: await blobsProvider.FromBlobAsync(destinationBlobUri, new BlockBlobStorageResourceOptions()),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

استئناف عملية نقل موجودة

من خلال استمرار تقدم النقل إلى القرص، تسمح لك مكتبة Data Movement باستئناف عملية نقل فشلت قبل الاكتمال، أو تم إلغاؤها أو إيقافها مؤقتا. لاستئناف النقل، TransferManager يجب تكوين الكائن مع StorageResourceProvider مثيلات قادرة على إعادة تجميع النقل من البيانات المستمرة. يمكنك استخدام ProvidersForResuming خاصية فئة TransferManagerOptions لتحديد الموفرين.

يوضح مثال التعليمات البرمجية التالي كيفية تهيئة كائن TransferManager قادر على استئناف النقل بين نظام الملفات المحلي وتخزين Blob:

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions()
{
    ProvidersForResuming = new List<StorageResourceProvider>()
    {
        new BlobsStorageResourceProvider(tokenCredential)
    }
});

لاستئناف عملية نقل، اتصل بالأسلوب التالي:

TransferManager.ResumeTransferAsync

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

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

TransferOperation resumedTransfer = await transferManager.ResumeTransferAsync(transferId: ID);

إشعار

يختلف موقع بيانات النقل المستمر عن الموقع الافتراضي إذا تم تعيين TransferCheckpointStoreOptions كجزء من TransferManagerOptions. لاستئناف عمليات النقل المسجلة مع مخزن نقاط تفتيش مخصص، يجب توفير نفس خيارات مخزن نقاط التحقق للكائن TransferManager الذي يستأنف النقل.

مراقبة تقدم النقل

يمكن مراقبة عمليات النقل ومراقبتها من خلال عدة آليات، اعتمادا على احتياجات تطبيقك. في هذا القسم، ستتعلم كيفية مراقبة تقدم النقل باستخدام TransferOperation العنصر، وكيفية مراقبة النقل باستخدام TransferOptions الأحداث.

مثال: مراقبة تقدم النقل باستخدام `TransferOperation` العنصر

يمكنك مراقبة تقدم النقل باستخدام الكائن الذي TransferOperation تم إرجاعه بواسطة StartTransferAsync الأسلوب . يمكنك أيضا استدعاء TransferManager.GetTransfersAsync لتعداد كافة عمليات النقل لعنصر TransferManager .

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

async Task CheckTransfersAsync(TransferManager transferManager)
{
    await foreach (TransferOperation transfer in transferManager.GetTransfersAsync())
    {
        using StreamWriter logStream = File.AppendText("path/to/log/file");
        logStream.WriteLine(Enum.GetName(typeof(TransferState), transfer.Status.State));
    }
}

يحدد TransferStatus حالة مهمة النقل. TransferStatus يتضمن الخصائص التالية:

الخاصية	نوع	الوصف
`HasCompletedSuccessfully`	قيمة منطقية	يمثل إذا اكتمل النقل بنجاح دون أي فشل أو تخطي العناصر.
`HasFailedItems`	Boolean	يمثل ما إذا كان النقل يحتوي على أي عناصر فشل. إذا تم تعيينه إلى `true`، فإن النقل يحتوي على عنصر فشل واحد على الأقل. إذا تم تعيينه إلى `false`، فلن يكون للنقل حاليا أي فشل.
`HasSkippedItems`	Boolean	يمثل إذا كان النقل يحتوي على أي عناصر تم تخطيها. إذا تم تعيينه إلى `true`، فإن النقل يحتوي على عنصر واحد على الأقل تم تخطيه. إذا تم تعيينه إلى `false`، فلن يحتوي النقل حاليا على أي عناصر تم تخطيها. من الممكن عدم تخطي أي عناصر إذا `SkipIfExists` لم يتم تمكينها في TransferOptions.CreationMode.
`State`	TransferState	يحدد أنواع الحالة التي يمكن أن يحتويها النقل. راجع TransferState للحصول على التفاصيل.

مثال: مراقبة تقدم النقل باستخدام `TransferOptions` الأحداث

يمكنك مراقبة تقدم النقل من خلال الاستماع إلى الأحداث التي توفرها فئة TransferOptions . يتم تمرير المثيل TransferOptions إلى StartTransferAsync الأسلوب ويوفر الأحداث التي يتم تشغيلها عند اكتمال النقل أو فشله أو تخطيه أو تغيير الحالة.

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

async Task<TransferOperation> ListenToTransfersAsync(
    TransferManager transferManager,
    StorageResource source,
    StorageResource destination)
{
    TransferOptions transferOptions = new();
    transferOptions.ItemTransferCompleted += (TransferItemCompletedEventArgs args) =>
    {
        using (StreamWriter logStream = File.AppendText("path/to/log/file"))
        {
            logStream.WriteLine($"File Completed Transfer: {args.Source.Uri.AbsoluteUri}");
        }
        return Task.CompletedTask;
    };
    return await transferManager.StartTransferAsync(
        source,
        destination,
        transferOptions);
}

استخدام أساليب الامتداد ل `BlobContainerClient`

بالنسبة للتطبيقات ذات التعليمات البرمجية الموجودة التي تستخدم BlobContainerClient الفئة من Azure.Storage.Blobs، يمكنك استخدام أساليب الامتداد لبدء عمليات النقل مباشرة من كائن BlobContainerClient . يتم توفير أساليب الملحق في فئة BlobContainerClientExtensions (أو ShareDirectoryClientExtensions لملفات Azure)، وتوفر بعض فوائد استخدام TransferManager مع الحد الأدنى من تغييرات التعليمات البرمجية. في هذا القسم، ستتعلم كيفية استخدام أساليب الامتداد لإجراء عمليات النقل من كائن BlobContainerClient .

تثبيت حزمة Azure.Storage.Blobs إذا لم يكن لديك بالفعل:

dotnet add package Azure.Storage.Blobs

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

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;

يوضح مثال التعليمات البرمجية التالي كيفية إنشاء BlobContainerClient مثيل لحاوية كائن ثنائي كبير الحجم باسم sample-container:

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobServiceClient client = new BlobServiceClient(
    new Uri("https://<storage-account-name>.blob.core.windows.net"),
    tokenCredential);

BlobContainerClient containerClient = client.GetBlobContainerClient("sample-container");

يوضح مثال التعليمات البرمجية التالي كيفية تحميل محتويات الدليل المحلي لاستخدام sample-containerUploadDirectoryAsync:

TransferOperation transfer = await containerClient
    .UploadDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

يوضح مثال التعليمات البرمجية التالي كيفية تنزيل محتويات sample-container إلى دليل محلي باستخدام DownloadToDirectoryAsync:

TransferOperation transfer = await containerClient
    .DownloadToDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

لمعرفة المزيد حول أساليب الملحق ل BlobContainerClient، راجع الملحقات على BlobContainerClient.

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

تتوفر نماذج التعليمات البرمجية ل DataMovement.Blobs وDataMovement.Files.Shares في Azure SDK لمستودع .NET GitHub.

مشاركة عبر

نقل البيانات باستخدام Data Movement library

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

إعداد بيئتك

تثبيت الحزم

أضف توجيهات using

التصريح

نبذة عن مكتبة Data Movement

إنشاء كائن TransferManager

إنشاء كائن StorageResource

إنشاء كائن StorageResource ل Blob Storage