Unggah blob dengan .NET

Artikel ini memperlihatkan cara mengunggah blob menggunakan pustaka klien Azure Storage untuk .NET. Anda dapat mengunggah data ke blob blok dari jalur file, aliran, objek biner, atau string teks. Anda juga dapat membuka aliran blob dan menulis ke dalamnya, atau mengunggah blob besar dalam blok.

Prasyarat

Langganan Azure - buat akun secara gratis
Akun penyimpanan Azure - buat akun penyimpanan
.NET SDK terbaru untuk sistem operasi Anda. Pastikan untuk mendapatkan SDK dan bukan runtime.

Atur 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. Untuk detailnya, lihat Mulai menggunakan Azure Blob Storage dan .NET.

Memasang paket

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

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

Tambahkan direktif `using`

Tambahkan arahan ini using ke bagian atas file kode Anda:

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

Beberapa contoh kode dalam artikel ini mungkin memerlukan arahan tambahan using .

Membuat objek klien

Untuk menyambungkan aplikasi ke Blob Storage, buat instans BlobServiceClient. Contoh berikut menunjukkan cara membuat objek klien menggunakan DefaultAzureCredential untuk otorisasi:

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

    return client;
}

Anda dapat mendaftarkan klien layanan untuk injeksi dependensi di aplikasi .NET.

Anda juga dapat membuat objek klien untuk kontainer atau blob tertentu. Untuk mempelajari selengkapnya tentang membuat dan mengelola objek klien, lihat Membuat dan mengelola objek klien yang berinteraksi dengan sumber daya data.

Otorisasi

Mekanisme otorisasi harus memiliki izin yang diperlukan untuk mengunggah blob. Untuk otorisasi dengan Microsoft Entra ID (disarankan), Anda memerlukan peran bawaan Azure RBAC Storage Blob Data Contributor atau yang lebih tinggi. Untuk mempelajari lebih lanjut, lihat panduan otorisasi untuk Put Blob (REST API) dan Put Block (REST API).

Mengunggah data ke blok blob

Anda dapat menggunakan salah satu metode berikut untuk mengunggah data ke blob blok:

Saat menggunakan metode unggahan ini, pustaka klien dapat memanggil Put Blob atau serangkaian panggilan Put Block diikuti oleh Put Block List. Perilaku ini tergantung pada ukuran keseluruhan objek dan bagaimana opsi transfer data diatur.

Untuk membuka aliran di Blob Storage dan menulis ke aliran tersebut, gunakan salah satu metode berikut:

Catatan

Pustaka klien Azure Storage tidak mendukung penulisan bersamaan ke blob yang sama. Jika aplikasi Anda memerlukan beberapa proses yang menulis ke blob yang sama, Anda harus menerapkan strategi untuk kontrol konkurensi untuk memberikan pengalaman yang dapat diprediksi. Untuk mempelajari selengkapnya tentang strategi konkurensi, lihat Mengelola konkurensi di Blob Storage.

Mengunggah block blob dari jalur file lokal

Contoh berikut ini mengunggah sebuah blob blok dari jalur file lokal:

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

Mengunggah blok blob dari aliran

Contoh berikut mengunggah blob blok dengan membuat objek Stream dan mengunggah aliran.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

Mengunggah blok blob dari objek BinaryData

Contoh berikut mengunggah blok blob dari BinaryData objek.

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

Unggah blob blok dari string

Contoh berikut ini mengunggah blok blob dari sebuah string:

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

Mengunggah ke aliran di Blob Storage

Anda dapat membuka aliran di dalam Blob Storage dan menuliskannya. Contoh berikut membuat file zip di Blob Storage dan menulis file ke dalamnya. Sebagai ganti dari membuat file zip di memori lokal, hanya satu file dalam satu waktu yang ada di memori.

Peringatan

Pendekatan ini bisa sangat mahal jika kebijakan replikasi objek diaktifkan karena setiap penulisan ke aliran membuat versi baru file zip, dan setiap versi disalin ke akun tujuan. Hal yang sama berlaku jika pencadangan Azure Blob vaulted diaktifkan karena pencadangan vaulted menggunakan replikasi objek.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

Mengunggah blok blob dengan opsi konfigurasi

Anda dapat menentukan opsi konfigurasi pustaka klien saat mengunggah blob. Opsi ini dapat disetel untuk meningkatkan performa, meningkatkan keandalan, dan mengoptimalkan biaya. Contoh kode berikut menunjukkan cara menggunakan BlobUploadOptions untuk menentukan opsi konfigurasi saat memanggil metode pengunggahan.

Tentukan opsi transfer data saat diunggah

Anda dapat mengonfigurasi nilai di StorageTransferOptions untuk meningkatkan performa operasi transfer data. Contoh kode berikut menunjukkan cara mengatur nilai untuk StorageTransferOptions dan menyertakan opsi sebagai bagian BlobUploadOptions dari instans. Nilai yang disediakan dalam sampel ini tidak dimaksudkan untuk menjadi rekomendasi. Untuk menyetel nilai-nilai ini dengan benar, Anda perlu mempertimbangkan kebutuhan spesifik aplikasi Anda.

public static async Task UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Untuk mempelajari selengkapnya tentang menyetel opsi transfer data, lihat Penyetelan performa untuk unggahan dan unduhan dengan .NET.

Tentukan opsi validasi transfer saat diunggah

Anda dapat menentukan opsi validasi transfer untuk membantu memastikan bahwa data diunggah dengan benar dan belum diubah selama transit. Opsi validasi transfer dapat ditentukan di tingkat klien menggunakan BlobClientOptions, yang menerapkan opsi validasi ke semua metode yang dipanggil dari instans BlobClient .

Anda juga dapat mengganti opsi validasi transfer di tingkat metode menggunakan BlobUploadOptions. Contoh kode berikut menunjukkan cara membuat BlobUploadOptions objek dan menentukan algoritma untuk membuat checksum. Checksum kemudian digunakan oleh layanan untuk memverifikasi integritas data konten yang diunggah.

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Tabel berikut ini memperlihatkan opsi yang tersedia untuk algoritma checksum, seperti yang ditentukan oleh StorageChecksumAlgorithm:

Nama	Value	Deskripsi
Auto	0	Disarankan. Memungkinkan pustaka memilih algoritma. Versi pustaka yang berbeda dapat memilih algoritma yang berbeda.
Tidak	1	Tidak ada algoritma yang dipilih. Jangan hitung atau minta checksum.
MD5	2	Algoritma hash MD5 standar.
StorageCrc64	3	CRC 64-bit kustom Azure Storage.

Catatan

Jika checksum yang ditentukan dalam permintaan tidak cocok dengan checksum yang dihitung oleh layanan, operasi pengunggahan gagal. Operasi tidak diulang ketika menggunakan kebijakan pengulangan bawaan. Tergantung pada algoritma mana yang digunakan, .NET akan menyebabkan RequestFailedException dilemparkan dengan kode status 400 dan kode kesalahan Md5Mismatch atau Crc64Mismatch.

Mengunggah dengan tag indeks

Tag indeks blob mengategorikan data di akun penyimpanan Anda menggunakan atribut tag nilai kunci. Tag ini secara otomatis diindeks dan diekspos sebagai indeks multi-dimensi yang dapat dicari untuk menemukan data dengan mudah. Anda dapat menambahkan tag ke instans BlobUploadOptions dan meneruskan instans tersebut ke dalam metode UploadAsync.

Contoh berikut mengunggah blok blob dengan tag indeks.

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

Mengatur tingkat akses blob saat diunggah

Anda dapat mengatur tingkat akses blob saat diunggah dengan menggunakan kelas BlobUploadOptions . Contoh kode berikut menunjukkan cara mengatur tingkat akses saat mengunggah blob:

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Mengatur tingkat akses hanya diperbolehkan untuk blob blok. Anda dapat mengatur tingkat akses untuk blok blob ke Hot, Cool, Cold, atau Archive. Untuk mengatur tingkat akses ke Cold, Anda harus menggunakan versi pustaka klien minimum 12.15.0.

Untuk mempelajari selengkapnya tentang tingkat akses, lihat Gambaran umum tingkat akses.

Unggah blok blob dengan mempersiapkan blok dan mengonfirmasikannya

Anda dapat memiliki kontrol yang lebih besar atas cara membagi unggahan menjadi blok dengan melakukan penahapan data secara manual. Ketika semua blok yang membentuk blob disiapkan, Anda dapat memasukkannya ke Blob Storage. Anda dapat menggunakan pendekatan ini untuk meningkatkan performa dengan mengunggah blok secara paralel.

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

Sumber

Untuk mempelajari selengkapnya tentang mengunggah blob menggunakan pustaka klien Azure Blob Storage untuk .NET, lihat sumber daya berikut ini.

Sampel kode

Menampilkan sampel kode dari artikel ini (GitHub)

Operasi REST API

Azure SDK untuk .NET berisi pustaka yang dibangun di atas Azure REST API, memungkinkan Anda berinteraksi dengan operasi REST API melalui paradigma .NET yang sudah dikenal. Metode pustaka klien untuk mengunggah blob menggunakan operasi REST API berikut:

Unggah Blob (REST API)
Put Block (API REST)

Lihat juga

Artikel ini adalah bagian dari panduan pengembang Blob Storage untuk .NET. Untuk mempelajari lebih lanjut, lihat daftar lengkap artikel panduan pengembang di Membangun aplikasi .NET Anda.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-02