Sdílet prostřednictvím

Nahrání objektu blob pomocí .NET

  • Článek

Tento článek ukazuje, jak nahrát objekt blob pomocí klientské knihovny Azure Storage pro .NET. Data můžete nahrát do objektu blob bloku z cesty k souboru, datového proudu, binárního objektu nebo textového řetězce. Můžete také otevřít datový proud objektů blob a zapisovat do něj nebo do bloků nahrát velké objekty blob.

Požadavky

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro .NET. Kroky zahrnují instalaci balíčku, přidání using direktiv a vytvoření autorizovaného objektu klienta. Podrobnosti najdete v tématu Začínáme se službou Azure Blob Storage a .NET.

Instalace balíčků

Z adresáře projektu nainstalujte balíčky pro klientské knihovny Azure Blob Storage a Azure Identity pomocí dotnet add package příkazu. Balíček Azure.Identity je potřeba pro připojení bez hesla ke službám Azure.

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

Přidání using direktiv

Na začátek souboru kódu přidejte tyto using direktivy:

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

Některé příklady kódu v tomto článku mohou vyžadovat další using direktivy.

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient. Následující příklad ukazuje, jak vytvořit objekt klienta pro DefaultAzureCredential autorizaci:

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

    return client;
}

Klienta služby můžete zaregistrovat pro injektáž závislostí v aplikaci .NET.

Můžete také vytvořit klientské objekty pro konkrétní kontejnery nebo objekty blob. Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k nahrání objektu blob. K autorizaci pomocí Microsoft Entra ID (doporučeno) potřebujete předdefinovanou roli Přispěvatel dat objektů blob služby Azure RBAC nebo vyšší. Další informace najdete v pokynech k autorizaci pro Put Blob (REST API) a Put Block (REST API).

Nahrání dat do objektu blob bloku

K nahrání dat do objektu blob bloku můžete použít některou z následujících metod:

Při použití těchto metod nahrávání může klientská knihovna volat put blob nebo řadu volání Put Block následované Put Block List. Toto chování závisí na celkové velikosti objektu a způsobu nastavení možností přenosu dat.

K otevření datového proudu ve službě Blob Storage a zápisu do tohoto datového proudu použijte některou z následujících metod:

Nahrání objektu blob bloku z místní cesty k souboru

Následující příklad nahraje objekt blob bloku z místní cesty k souboru:

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

    await blobClient.UploadAsync(localFilePath, true);
}

Nahrání objektu blob bloku ze streamu

Následující příklad nahraje objekt blob bloku vytvořením objektu Stream a nahráním datového proudu.

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

Nahrání objektu blob bloku z objektu BinaryData

Následující příklad nahraje objekt blob bloku z objektu 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();
}

Nahrání objektu blob bloku z řetězce

Následující příklad nahraje objekt blob bloku z řetězce:

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

Nahrání do datového proudu ve službě Blob Storage

Stream můžete otevřít ve službě Blob Storage a zapisovat do něj. Následující příklad vytvoří soubor ZIP ve službě Blob Storage a zapíše do něj soubory. Místo sestavení souboru ZIP v místní paměti je v paměti pouze jeden soubor najednou.

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

Nahrání objektu blob bloku s možnostmi konfigurace

Při nahrávání objektu blob můžete definovat možnosti konfigurace klientské knihovny. Tyto možnosti je možné ladit, aby se zlepšil výkon, zlepšila spolehlivost a optimalizovala náklady. Následující příklady kódu ukazují, jak pomocí BlobUploadOptions definovat možnosti konfigurace při volání metody upload.

Určení možností přenosu dat při nahrání

Hodnoty v StorageTransferOptions můžete nakonfigurovat tak, aby se zlepšil výkon operací přenosu dat. Následující příklad kódu ukazuje, jak nastavit hodnoty a StorageTransferOptions zahrnout možnosti jako součást BlobUploadOptions instance. Hodnoty uvedené v této ukázce nejsou určené jako doporučení. Pokud chcete tyto hodnoty správně vyladit, musíte zvážit konkrétní potřeby vaší aplikace.

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

Další informace o ladění možností přenosu dat najdete v tématu Ladění výkonu pro nahrávání a stahování pomocí .NET.

Určení možností ověření přenosu při nahrání

Můžete zadat možnosti ověření přenosu, které vám pomůžou zajistit, aby se data nahrála správně a nebyla během přenosu manipulována. Možnosti ověření přenosu je možné definovat na úrovni klienta pomocí Objektů blobClientOptions, které používají možnosti ověřování pro všechny metody volané z instance BlobClient .

Můžete také přepsat možnosti ověřování přenosu na úrovni metody pomocí BlobUploadOptions. Následující příklad kódu ukazuje, jak vytvořit BlobUploadOptions objekt a zadat algoritmus pro generování kontrolního součtu. Kontrolní součet pak služba použije k ověření integrity dat nahraného obsahu.

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

Následující tabulka ukazuje dostupné možnosti pro algoritmus kontrolního součtu, jak je definováno storageChecksumAlgorithm:

Jméno Hodnota Popis
Automaticky 0 Doporučený způsob: Umožňuje knihovně zvolit algoritmus. Různé verze knihoven můžou zvolit různé algoritmy.
Nic 0 Žádný vybraný algoritmus. Nevypočítávejte kontrolní součty ani nepožadujte.
MD5 2 Standardní hashovací algoritmus MD5
StorageCrc64 3 Vlastní 64bitová verze CRC služby Azure Storage

Poznámka:

Pokud kontrolní součet zadaný v požadavku neodpovídá kontrolnímu součtu vypočítaného službou, operace nahrávání selže. Operace se při použití výchozích zásad opakování nepokusí znovu. V .NET RequestFailedException je vyvolán se stavovým kódem 400 a kódem Md5Mismatch chyby nebo Crc64Mismatchv závislosti na tom, který algoritmus se používá.

Nahrání se značkami indexu

Značky indexu objektů blob kategorizují data v účtu úložiště pomocí atributů značek klíč-hodnota. Tyto značky se automaticky indexují a zveřejňují jako prohledávatelný multidimenzionální index, aby bylo možné snadno najít data. Do instance BlobUploadOptions můžete přidat značky a předat tuto instanci do UploadAsync metody.

Následující příklad nahraje objekt blob bloku se značkami indexu:

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

Nastavení úrovně přístupu k objektu blob při nahrání

Úroveň přístupu objektu blob můžete nastavit při nahrávání pomocí třídy BlobUploadOptions . Následující příklad kódu ukazuje, jak nastavit úroveň přístupu při nahrávání objektu 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();
}

Nastavení úrovně přístupu je povolené jenom pro objekty blob bloku. Úroveň přístupu objektu blob bloku můžete nastavit na Hot, Cool, Coldnebo Archive. Pokud chcete nastavit úroveň přístupu, Coldmusíte použít minimální verzi klientské knihovny 12.15.0.

Další informace o úrovních přístupu najdete v tématu Přehled úrovní přístupu.

Nahrání objektu blob bloku přípravými bloky a potvrzením

Můžete mít větší kontrolu nad tím, jak rozdělit nahrávání do bloků ručním přípravou jednotlivých bloků dat. Když jsou všechny bloky, které tvoří objekt blob, připravené, můžete je potvrdit do služby Blob Storage. Tento přístup můžete použít k vylepšení výkonu paralelním nahráváním bloků.

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

Zdroje informací

Další informace o nahrávání objektů blob pomocí klientské knihovny azure Blob Storage pro .NET najdete v následujících zdrojích informací.

Ukázky kódu

Operace rozhraní REST API

Sada Azure SDK pro .NET obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat .NET. Metody klientské knihovny pro nahrávání objektů blob používají následující operace rozhraní REST API:

Viz také

Související obsah

  • Tento článek je součástí příručky pro vývojáře služby Blob Storage pro .NET. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace .NET.