Unggah blob dengan .NET

• .NET
• Java
• JavaScript
• TypeScript
• Python

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 menulisnya, atau mengunggah blob besar dalam blok.

Prasyarat

• Artikel ini mengasumsikan Anda sudah memiliki proyek yang disiapkan untuk bekerja dengan pustaka klien Azure Blob Storage untuk .NET. Untuk mempelajari tentang menyiapkan proyek Anda, termasuk penginstalan paket, menambahkan arahanusing, dan membuat objek klien resmi, lihat Mulai menggunakan Azure Blob Storage dan .NET.
• Mekanisme otorisasi harus memiliki izin untuk melakukan operasi unggahan. Untuk mempelajari lebih lanjut, lihat panduan otorisasi untuk operasi REST API berikut:
  • Masukkan Blob
  • Put Blok

Mengunggah data ke blob blok

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

• Unggah
• UploadAsync

Saat menggunakan metode pengunggahan 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:

• OpenWrite
• OpenWriteAsync

Mengunggah blob blok dari jalur file lokal

Contoh berikut mengunggah 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 blob blok dari aliran

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

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 blob blok dari objek BinaryData

Contoh berikut mengunggah blob blok dari objek BinaryData .

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

Mengunggah blob blok dari string

Contoh berikut mengunggah blob blok dari 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 Blob Storage dan menulisnya. 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.

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 blob blok 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 menyempurnakan 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 pada 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 dari 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	Nilai	Deskripsi
Otomatis	0	Disarankan. Memungkinkan pustaka untuk memilih algoritma. Versi pustaka yang berbeda dapat memilih algoritma yang berbeda.
Tidak ada	1	Tidak ada algoritma yang dipilih. Jangan menghitung atau meminta checksum.
MD5	2	Algoritma hash MD5 standar.
StorageCrc64	3	CRC kustom Azure Storage 64-bit.

Catatan

Jika checksum yang ditentukan dalam permintaan tidak cocok dengan checksum yang dihitung oleh layanan, operasi pengunggahan gagal. Operasi tidak dicoba kembali saat menggunakan kebijakan coba lagi default. Dalam .NET, RequestFailedException dilemparkan dengan kode status 400 dan kode Md5Mismatch kesalahan atau Crc64Mismatch, tergantung pada algoritma mana yang digunakan.

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 UploadAsync dalam metode .

Contoh berikut mengunggah blob blok 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 blob blok ke Hot, , CoolCold, 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 blob blok dengan blok penahapan dan penerapan

Anda dapat memiliki kontrol yang lebih besar atas cara membagi unggahan menjadi blok dengan melakukan pementasan blok 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.

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 familier. Metode pustaka klien untuk mengunggah blob menggunakan operasi REST API berikut:

• Memasukkan Blob (REST API)
• Put Block (REST API)

Sampel kode

• Lihat sampel kode dari artikel ini (GitHub)

Lihat juga

• Penyetelan performa untuk unggahan dan unduhan.
• Mengelola dan menemukan data Azure Blob dengan tag indeks blob
• Menggunakan tag indeks blob untuk mengelola dan menemukan data di Azure Blob Storage