Udostępnij za pośrednictwem

Przekazywanie obiektu blob przy użyciu platformy .NET

  • Artykuł

W tym artykule pokazano, jak przekazać obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla platformy .NET. Dane można przekazać do blokowego obiektu blob ze ścieżki pliku, strumienia, obiektu binarnego lub ciągu tekstowego. Możesz również otworzyć strumień obiektów blob i zapisać do niego lub przekazać duże obiekty blob w blokach.

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla platformy .NET. Kroki obejmują instalację pakietu, dodawanie using dyrektyw i tworzenie autoryzowanego obiektu klienta. Aby uzyskać szczegółowe informacje, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i .NET.

Instalowanie pakietów

Z katalogu projektu zainstaluj pakiety dla bibliotek klienta usługi Azure Blob Storage i tożsamości platformy Azure przy użyciu dotnet add package polecenia . Pakiet Azure.Identity jest wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

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

Dodawanie using dyrektyw

Dodaj te using dyrektywy na początku pliku kodu:

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

Niektóre przykłady kodu w tym artykule mogą wymagać dodatkowych using dyrektyw.

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie klasy BlobServiceClient. W poniższym przykładzie pokazano, jak utworzyć obiekt klienta przy użyciu DefaultAzureCredential autoryzacji:

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

    return client;
}

Możesz zarejestrować klienta usługi na potrzeby wstrzykiwania zależności w aplikacji .NET.

Można również tworzyć obiekty klienta dla określonych kontenerów lub obiektów blob. Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Autoryzacja

Mechanizm autoryzacji musi mieć niezbędne uprawnienia do przekazywania obiektu blob. Aby uzyskać autoryzację przy użyciu identyfikatora Entra firmy Microsoft (zalecane), potrzebujesz wbudowanej kontroli dostępu opartej na rolach platformy Azure współautora danych obiektów blob usługi Storage lub nowszego. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla funkcji Put Blob (interfejs API REST) i Put Block (interfejs API REST).

Przekazywanie danych do blokowego obiektu blob

Aby przekazać dane do blokowego obiektu blob, możesz użyć jednej z następujących metod:

W przypadku korzystania z tych metod przekazywania biblioteka klienta może wywoływać obiekt Put Blob lub serię wywołań Put Block, a następnie umieścić listę bloków. To zachowanie zależy od ogólnego rozmiaru obiektu i sposobu ustawiania opcji transferu danych.

Aby otworzyć strumień w usłudze Blob Storage i zapisać go w tym strumieniu, użyj jednej z następujących metod:

Przekazywanie blokowego obiektu blob ze ścieżki pliku lokalnego

Poniższy przykład przekazuje blokowy obiekt blob ze ścieżki pliku lokalnego:

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

    await blobClient.UploadAsync(localFilePath, true);
}

Przekazywanie blokowego obiektu blob ze strumienia

Poniższy przykład przekazuje blokowy obiekt blob przez utworzenie obiektu usługi Stream i przekazanie strumienia.

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

Przekazywanie blokowego obiektu blob z obiektu BinaryData

Poniższy przykład przekazuje blokowy obiekt blob z obiektu 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();
}

Przekazywanie blokowego obiektu blob z ciągu

Poniższy przykład przekazuje blokowy obiekt blob z ciągu:

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

Przekazywanie do strumienia w usłudze Blob Storage

Strumień można otworzyć w usłudze Blob Storage i zapisać w nim. Poniższy przykład tworzy plik zip w usłudze Blob Storage i zapisuje w nim pliki. Zamiast tworzyć plik zip w pamięci lokalnej, tylko jeden plik naraz jest w pamięci.

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

Przekazywanie blokowego obiektu blob przy użyciu opcji konfiguracji

Opcje konfiguracji biblioteki klienta można zdefiniować podczas przekazywania obiektu blob. Te opcje można dostosować, aby zwiększyć wydajność, zwiększyć niezawodność i zoptymalizować koszty. W poniższych przykładach kodu pokazano, jak używać obiektu BlobUploadOptions do definiowania opcji konfiguracji podczas wywoływania metody przekazywania.

Określanie opcji transferu danych podczas przekazywania

Możesz skonfigurować wartości w obszarze StorageTransferOptions , aby zwiększyć wydajność operacji transferu danych. Poniższy przykład kodu pokazuje, jak ustawić wartości dla StorageTransferOptions i uwzględnić opcje w ramach BlobUploadOptions wystąpienia. Wartości podane w tym przykładzie nie są przeznaczone do zalecenia. Aby prawidłowo dostosować te wartości, należy wziąć pod uwagę konkretne potrzeby aplikacji.

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

Aby dowiedzieć się więcej na temat dostrajania opcji transferu danych, zobacz Dostosowywanie wydajności przekazywania i pobierania za pomocą platformy .NET.

Określanie opcji weryfikacji transferu podczas przekazywania

Możesz określić opcje weryfikacji transferu, aby upewnić się, że dane są prawidłowo przekazywane i nie zostały naruszone podczas przesyłania. Opcje weryfikacji transferu można zdefiniować na poziomie klienta przy użyciu klasy BlobClientOptions, która stosuje opcje walidacji do wszystkich metod wywoływanych z wystąpienia obiektu BlobClient .

Można również zastąpić opcje weryfikacji transferu na poziomie metody przy użyciu obiektu BlobUploadOptions. W poniższym przykładzie kodu pokazano, jak utworzyć BlobUploadOptions obiekt i określić algorytm generowania sumy kontrolnej. Suma kontrolna jest następnie używana przez usługę do weryfikowania integralności danych przekazanej zawartości.

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

W poniższej tabeli przedstawiono dostępne opcje algorytmu sumy kontrolnej zdefiniowane przez storageChecksumAlgorithm:

Nazwa/nazwisko Wartość Opis
Automatycznie 0 Zalecane. Umożliwia bibliotece wybranie algorytmu. Różne wersje biblioteki mogą wybierać różne algorytmy.
Brak 1 Brak wybranego algorytmu. Nie obliczaj sum kontrolnych ani nie żądaj ich.
MD5 2 Standardowy algorytm skrótu MD5.
StorageCrc64 3 Niestandardowa 64-bitowa wersja CRC usługi Azure Storage.

Uwaga

Jeśli suma kontrolna określona w żądaniu nie jest zgodna z sumą kontrolną obliczoną przez usługę, operacja przekazywania zakończy się niepowodzeniem. Operacja nie jest ponawiana podczas korzystania z domyślnych zasad ponawiania. Na platformie .NET RequestFailedException jest zgłaszany kod stanu 400 i kod Md5Mismatch błędu lub Crc64Mismatch, w zależności od tego, który algorytm jest używany.

Przekazywanie za pomocą tagów indeksu

Tagi indeksu obiektów blob kategoryzują dane na koncie magazynu przy użyciu atrybutów tagów klucz-wartość. Te tagi są automatycznie indeksowane i uwidaczniane jako indeks wielowymiarowy z możliwością wyszukiwania w celu łatwego znajdowania danych. Tagi można dodać do wystąpienia obiektu BlobUploadOptions i przekazać to wystąpienie do UploadAsync metody .

Poniższy przykład przekazuje blokowy obiekt blob z tagami indeksu:

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

Ustawianie warstwy dostępu obiektu blob podczas przekazywania

Warstwę dostępu obiektu blob można ustawić podczas przekazywania przy użyciu klasy BlobUploadOptions . W poniższym przykładzie kodu pokazano, jak ustawić warstwę dostępu podczas przekazywania obiektu 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();
}

Ustawienie warstwy dostępu jest dozwolone tylko dla blokowych obiektów blob. Warstwę dostępu dla blokowego obiektu blob można ustawić na Hot, Cool, Coldlub Archive. Aby ustawić warstwę dostępu na Cold, należy użyć minimalnej wersji biblioteki klienta 12.15.0.

Aby dowiedzieć się więcej na temat warstw dostępu, zobacz Omówienie warstw dostępu.

Przekazywanie blokowego obiektu blob przez bloki przejściowe i zatwierdzanie

Możesz mieć większą kontrolę nad sposobem dzielenia przekazywania na bloki przez ręczne przemieszczanie poszczególnych bloków danych. Gdy wszystkie bloki tworzące obiekt blob są przygotowane, można je zatwierdzić w usłudze Blob Storage. Za pomocą tego podejścia można zwiększyć wydajność, przekazując bloki równolegle.

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

Zasoby

Aby dowiedzieć się więcej na temat przekazywania obiektów blob przy użyciu biblioteki klienta usługi Azure Blob Storage dla platformy .NET, zobacz następujące zasoby.

Przykłady kodu

Operacje interfejsu API REST

Zestaw Azure SDK dla platformy .NET zawiera biblioteki, które są oparte na interfejsie API REST platformy Azure, co umożliwia interakcję z operacjami interfejsu API REST za pomocą znanych paradygmatów platformy .NET. Metody biblioteki klienta do przekazywania obiektów blob używają następujących operacji interfejsu API REST:

Zobacz też

Powiązana zawartość

  • Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla platformy .NET. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji platformy .NET.