Nahrání blobu pomocí .NET

• .NET
• Java
• JavaScript
• Python
• Jít

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

Požadavky

• Předplatné Azure – vytvoření bezplatného předplatného
• Účet úložiště Azure – Vytvoření účtu úložiště
• Nejnovější .NET SDK pro váš operační systém Nezapomeňte získat sadu SDK a ne modul runtime.

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řidejte using direktivy

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 za účelem autorizace pomocí DefaultAzureCredential.

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

    return client;
}

Můžete zaregistrovat klienta služby pro dependency injection v .NET aplikaci.

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 integrovanou roli Azure RBAC Storage Blob Data Contributor 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:

• Nahrát
• UploadAsync

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:

• OpenWrite
• OpenWriteAsync

Poznámka:

Klientské knihovny Azure Storage nepodporují souběžné zápisy do stejného objektu blob. Pokud vaše aplikace vyžaduje více procesů zápisů do stejného objektu blob, měli byste implementovat strategii řízení souběžnosti, která poskytuje předvídatelné prostředí. Další informace o strategiích souběžnosti najdete v tématu Správa souběžnosti ve službě Blob Storage.

Nahrání blokového blobu z místní souborové cesty

Následující příklad nahraje blokový blob z cesty místního 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í bloku blobu ze streamu

Následující příklad nahraje blokový blob vytvořením objektu Stream a nahráním 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át blokový blob z objektu BinaryData

Následující příklad nahraje blokový objekt blob 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át blokový blob ze stringu

Následující příklad nahraje blokový blob 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.

Výstraha

Tento přístup může být velmi nákladný, pokud je povolená zásada replikace objektů, protože každý zápis do datového proudu vytvoří novou verzi souboru ZIP a každá verze se zkopíruje do cílového účtu. Totéž platí, pokud je povolené zálohování trezoru objektů blob v Azure, protože trezorované zálohování používá replikaci objektů.

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í bloku typu blob 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 pro StorageTransferOptions a zahrnout možnosti jako součást instance BlobUploadOptions. 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í BlobClientOptions, který aplikuje možnosti ověřování na 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
Auto	0	Doporučeno. Umožňuje knihovně zvolit algoritmus. Různé verze knihoven můžou zvolit různé algoritmy.
None	1	Žádný vybraný algoritmus. Nevypočítávejte kontrolní součty ani je 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í zásady opakování neopakuje. V prostředí .NET je RequestFailedException vyvolán se stavovým kódem 400 a chybovým kódem Md5Mismatch nebo Crc64Mismatch, v 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ů klíčů a hodnot. 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 tuto instanci předat do UploadAsync metody.

Následující příklad nahraje blokový blob 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);
}

Nastavte úroveň přístupu 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í blobu:

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 blokové objekty blob. Úroveň přístupu objektu blob bloku můžete nastavit na Hot, Cool, Coldnebo Archive. Pokud chcete nastavit úroveň přístupu Cold, musí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í blokového blobu přípravou bloků a potvrzením

Můžete mít větší kontrolu nad tím, jak rozdělovat nahrávání do bloků ručním nastavením 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

• Zobrazení ukázek kódu z tohoto článku (GitHub)

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:

• Vložení objektu blob (REST API)
• Put Block (REST API)

Viz také

• Ladění výkonu pro nahrávání a stahování
• Spravujte a nalézejte data Azure Blob pomocí indexačních značek
• Použití značek indexu objektů blob ke správě a hledání dat ve službě Azure Blob Storage

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.