Baca dalam bahasa Inggris

Bagikan melalui

Transfer data dengan pustaka Data Movement

  • Artikel

Pustaka Azure Storage Data Movement adalah pustaka sumber terbuka lintas platform yang dirancang untuk pengunggahan, pengunduhan, dan penyalinan blob dan file berperforma tinggi. Pustaka Data Movement menyediakan metode mudah yang tidak tersedia di pustaka klien Azure Storage untuk .NET. Metode ini memungkinkan Anda mengatur jumlah operasi paralel, melacak kemajuan transfer, melanjutkan transfer yang dibatalkan, dan banyak lagi.

Pustaka Pergerakan Data hanya tersedia untuk .NET, dan hanya mendukung Azure Blob Storage dan Azure Files. Anda harus mempertimbangkan batasan ini dan masalah lain yang diketahui saat memutuskan apakah akan menggunakan pustaka Pergerakan Data.

Jika Anda memigrasikan kode dari pustaka Microsoft.Azure.Storage.DataMovement yang lebih lama (versi 2.X.X) ke pustaka Azure.Storage.DataMovement saat ini (versi 12.X.X), lihat Panduan migrasi.

Dokumen referensi | API Paket kode | sumber (NuGet) | Sampel: Blobs / Files.Shares

Prasyarat

Menyiapkan lingkungan Anda

Jika Anda tidak memiliki proyek yang sudah ada, bagian ini menunjukkan kepada Anda cara menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk .NET. Langkah-langkahnya termasuk penginstalan paket, menambahkan arahan using , dan membuat objek klien resmi.

Memasang paket

Dari direktori proyek Anda, instal paket untuk pustaka klien Azure Storage Data Movement dan pustaka klien Azure Identity menggunakan dotnet add package perintah . Paket Azure.Identity diperlukan untuk koneksi tanpa kata sandi ke layanan Azure.

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

Untuk bekerja dengan pustaka ekstensi untuk Azure Files, instal paket Azure.Storage.DataMovement.Files.Shares :

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

Tambahkan direktif using

Untuk menjalankan contoh kode dalam artikel ini, tambahkan arahan berikut using :

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

Jika Anda menggunakan pustaka ekstensi untuk Azure Files, tambahkan direktif berikut using :

using Azure.Storage.DataMovement.Files.Shares;

Authorization

Mekanisme otorisasi harus memiliki izin yang diperlukan untuk melakukan operasi unggah, unduh, atau salin. Untuk otorisasi dengan MICROSOFT Entra ID (disarankan), Anda memerlukan peran bawaan Azure RBAC Kontributor Data Blob Penyimpanan atau yang lebih tinggi.

Tentang pustaka Pergerakan Data

Pustaka Pergerakan Data Azure Storage terdiri dari pustaka klien umum, dan pustaka ekstensi untuk Azure Blob Storage dan Azure Files. Pustaka umum menyediakan fungsionalitas inti untuk mentransfer data, sementara pustaka ekstensi menyediakan fungsionalitas khusus untuk Blob Storage dan Azure Files. Untuk mempelajari selengkapnya, lihat sumber daya berikut:

Membuat TransferManager objek

TransferManager adalah kelas utama untuk memulai dan mengontrol semua jenis transfer, termasuk unggah, unduh, dan salin. Di bagian ini, Anda mempelajari cara membuat TransferManager objek untuk bekerja dengan sistem file lokal, Blob Storage, atau Azure Files.

Catatan

Praktik terbaik untuk manajemen klien Azure SDK adalah memperlakukan klien sebagai singleton, yang berarti bahwa kelas hanya memiliki satu objek pada satu waktu. Tidak perlu menyimpan lebih dari satu instans klien untuk serangkaian parameter konstruktor atau opsi klien tertentu.

Kode berikut menunjukkan cara membuat TransferManager objek:

TransferManager transferManager = new(new TransferManagerOptions());

Anda dapat secara opsional menyediakan instans TransferManagerOptions ke konstruktor, yang menerapkan opsi konfigurasi tertentu untuk semua transfer yang dimulai oleh TransferManager objek. Opsi konfigurasi berikut tersedia:

  • CheckpointStoreOptions: Opsional. Menentukan opsi untuk membuat titik pemeriksaan yang digunakan untuk menyimpan status transfer sehingga transfer dapat dilanjutkan.
  • Diagnostik: Mendapatkan opsi diagnostik manajer transfer.
  • ErrorHandling: Opsional. Menentukan bagaimana kesalahan ditangani selama transfer. Defaultnya adalah StopOnAnyFailure.
  • MaximumConcurrency: Jumlah maksimum pekerja yang dapat digunakan dalam transfer paralel.
  • ProvidersForResuming: Penyedia sumber daya untuk digunakan manajer transfer dalam memulai kembali transfer. Mengharapkan satu penyedia untuk setiap penyedia penyimpanan yang digunakan. Untuk mempelajari selengkapnya, lihat Melanjutkan transfer yang sudah ada.

Membuat StorageResource objek

StorageResource adalah kelas dasar untuk semua sumber daya penyimpanan, termasuk blob dan file. Untuk membuat StorageResource objek, gunakan salah satu kelas penyedia berikut:

Membuat StorageResource objek untuk Blob Storage

Kode berikut menunjukkan cara membuat StorageResource objek untuk kontainer blob dan blob menggunakan 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

Anda juga dapat membuat StorageResource objek menggunakan objek klien dari 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

Memulai transfer baru

Semua transfer perlu menentukan sumber dan tujuan. Sumber dan tujuan adalah jenis StorageResource, yang dapat berupa StorageResourceContainer atau StorageResourceItem. Untuk transfer tertentu, sumber dan tujuan harus dalam jenis yang sama. Misalnya, jika sumbernya adalah kontainer blob, tujuannya harus berupa kontainer blob.

Anda dapat memulai transfer baru dengan memanggil metode berikut:

Metode ini mengembalikan objek TransferOperation yang mewakili transfer. Anda dapat menggunakan TransferOperation objek untuk memantau kemajuan transfer atau mendapatkan ID transfer. ID transfer adalah pengidentifikasi unik untuk transfer yang diperlukan untuk melanjutkan transfer atau menjeda transfer.

Anda dapat secara opsional menyediakan instans TransferOptions ke StartTransferAsync atau ResumeTransferAsync, yang menerapkan opsi konfigurasi tertentu ke transfer tertentu. Opsi konfigurasi berikut tersedia:

  • CreationMode: Mengonfigurasi perilaku saat transfer menemukan sumber daya yang sudah ada. Default ke FailIfExists saat memulai transfer baru. Saat Anda melanjutkan transfer, defaultnya dapat bervariasi. Untuk semua sumber daya yang berhasil dijumlahkan saat transfer dimulai, CreationMode default ke nilai awal yang digunakan. Untuk sumber daya yang tersisa, nilai default reguler berlaku.
  • InitialTransferSize: Ukuran permintaan rentang pertama dalam byte. Ukuran transfer tunggal yang lebih kecil dari batas ini diunggah atau diunduh dalam satu permintaan. Transfer yang lebih besar dari batas ini terus diunduh atau diunggah dalam potongan ukuran MaximumTransferChunkSize. Nilai defaultnya adalah 32 MiB. Saat Anda melanjutkan transfer, nilai default adalah nilai yang ditentukan saat transfer pertama kali dimulai.
  • MaximumTransferChunkSize: Ukuran maksimum yang digunakan untuk setiap gugus saat mentransfer data dalam gugus. Nilai defaultnya adalah 4 MiB. Saat Anda melanjutkan transfer, nilai default adalah nilai yang ditentukan saat transfer pertama kali dimulai.
  • ProgressHandlerOptions: Opsional. Opsi untuk mengubah perilaku ProgressHandler.

Contoh: Mengunggah direktori lokal ke kontainer blob

Contoh kode berikut menunjukkan cara memulai transfer baru untuk mengunggah direktori lokal ke kontainer blob:

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

Contoh: Menyalin kontainer atau blob

Anda dapat menggunakan pustaka Pergerakan Data untuk menyalin antara dua StorageResource instans. Untuk sumber daya blob, transfer menggunakan operasi Put Blob From URL , yang melakukan salinan server-ke-server.

Contoh kode berikut menunjukkan cara memulai transfer baru untuk menyalin semua blob dalam kontainer blob sumber ke kontainer blob tujuan. Kontainer tujuan harus sudah ada. Dalam contoh ini, kami mengatur CreationMode ke OverwriteIfExists untuk menimpa blob tujuan apa pun yang sudah ada. Anda dapat menyesuaikan CreationMode properti berdasarkan kebutuhan aplikasi Anda.

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();

Contoh kode berikut menunjukkan cara memulai transfer baru untuk menyalin blob sumber ke blob tujuan. Dalam contoh ini, kami mengatur CreationMode ke OverwriteIfExists untuk menimpa blob tujuan jika sudah ada. Anda dapat menyesuaikan CreationMode properti berdasarkan kebutuhan aplikasi Anda.

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();

Melanjutkan transfer yang sudah ada

Dengan mempertahankan kemajuan transfer ke disk, pustaka Pergerakan Data memungkinkan Anda untuk melanjutkan transfer yang gagal sebelum selesai, atau dibatalkan atau dijeda. Untuk melanjutkan transfer, TransferManager objek harus dikonfigurasi dengan StorageResourceProvider instans yang mampu menyusun ulang transfer dari data yang bertahan. Anda dapat menggunakan ProvidersForResuming properti kelas TransferManagerOptions untuk menentukan penyedia.

Contoh kode berikut menunjukkan cara menginisialisasi TransferManager objek yang mampu melanjutkan transfer antara sistem file lokal dan Blob Storage:

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

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

Untuk melanjutkan transfer, panggil metode berikut:

Berikan ID transfer transfer yang ingin Anda lanjutkan. ID transfer adalah pengidentifikasi unik untuk transfer yang dikembalikan sebagai bagian TransferOperation dari objek saat transfer dimulai. Jika Anda tidak mengetahui nilai ID transfer, Anda dapat memanggil TransferManager.GetTransfersAsync untuk menemukan transfer dan ID yang sesuai.

Contoh kode berikut menunjukkan cara melanjutkan transfer:

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

Catatan

Lokasi data transfer yang dipertahankan berbeda dari lokasi default jika TransferCheckpointStoreOptions diatur sebagai bagian TransferManagerOptionsdari . Untuk melanjutkan transfer yang direkam dengan penyimpanan titik pemeriksaan kustom, Anda harus menyediakan opsi penyimpanan titik pemeriksaan yang sama untuk TransferManager objek yang melanjutkan transfer.

Memantau kemajuan transfer

Transfer dapat dipantau dan diamati melalui beberapa mekanisme, tergantung pada kebutuhan aplikasi Anda. Di bagian ini, Anda mempelajari cara memantau kemajuan transfer menggunakan TransferOperation objek, dan cara memantau transfer menggunakan TransferOptions peristiwa.

Contoh: Memantau kemajuan transfer menggunakan TransferOperation objek

Anda dapat memantau kemajuan transfer menggunakan objek yang TransferOperation dikembalikan oleh StartTransferAsync metode . Anda juga dapat memanggil TransferManager.GetTransfersAsync untuk menghitung semua transfer untuk TransferManager objek.

Contoh kode berikut menunjukkan cara melakukan iterasi atas semua transfer dan menulis status setiap transfer ke file log:

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 mendefinisikan status pekerjaan transfer. TransferStatus termasuk properti berikut:

Properti Tipe Deskripsi
HasCompletedSuccessfully Boolean Mewakili apakah transfer berhasil diselesaikan tanpa kegagalan atau item yang dilewati.
HasFailedItems Boolean Mewakili apakah transfer memiliki item kegagalan. Jika diatur ke true, transfer memiliki setidaknya satu item kegagalan. Jika diatur ke false, transfer saat ini tidak memiliki kegagalan.
HasSkippedItems Boolean Mewakili apakah transfer memiliki item yang dilewati. Jika diatur ke true, transfer memiliki setidaknya satu item yang dilewati. Jika diatur ke false, transfer saat ini tidak memiliki item yang dilewati. Dimungkinkan untuk tidak pernah memiliki item apa pun yang dilewati jika SkipIfExists tidak diaktifkan di TransferOptions.CreationMode.
State TransferState Menentukan jenis status yang dapat dimiliki transfer. Lihat TransferState untuk detailnya.

Contoh: Memantau kemajuan transfer menggunakan TransferOptions peristiwa

Anda dapat memantau kemajuan transfer dengan mendengarkan peristiwa yang disediakan oleh kelas TransferOptions . TransferOptions Instans diteruskan ke StartTransferAsync metode dan menyediakan peristiwa yang dipicu ketika transfer selesai, gagal, dilewati, atau mengubah status.

Contoh kode berikut menunjukkan cara mendengarkan peristiwa penyelesaian transfer menggunakan 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);
}

Menggunakan metode ekstensi untuk BlobContainerClient

Untuk aplikasi dengan kode yang ada yang menggunakan BlobContainerClient kelas dari Azure.Storage.Blobs, Anda dapat menggunakan metode ekstensi untuk memulai transfer langsung dari BlobContainerClient objek. Metode ekstensi disediakan di kelas BlobContainerClientExtensions (atau ShareDirectoryClientExtensions untuk Azure Files), dan memberikan beberapa manfaat menggunakan TransferManager dengan perubahan kode minimal. Di bagian ini, Anda mempelajari cara menggunakan metode ekstensi untuk melakukan transfer dari BlobContainerClient objek.

Instal paket Azure.Storage.Blobs jika Anda belum memilikinya:

dotnet add package Azure.Storage.Blobs

Tambahkan arahan berikut using ke bagian atas file kode Anda:

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

Contoh kode berikut menunjukkan cara membuat BlobContainerClient instans untuk kontainer blob bernama 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");

Contoh kode berikut menunjukkan cara mengunggah konten direktori lokal untuk sample-container menggunakan UploadDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Contoh kode berikut menunjukkan cara mengunduh konten sample-container ke direktori lokal menggunakan DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Untuk mempelajari selengkapnya tentang metode ekstensi untuk BlobContainerClient, lihat Ekstensi di BlobContainerClient.

Langkah selanjutnya