Przekazywanie obiektu blob przy użyciu platformy .NET

• .NET
• Java
• JavaScript
• TypeScript
• Python

W tym artykule pokazano, jak przekazać obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla platformy .NET. Dane można przekazywać 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ć go lub przekazać duże obiekty blob w blokach.

Wymagania wstępne

• W tym artykule założono, że masz już skonfigurowany projekt do pracy z biblioteką klienta Azure Blob Storage dla platformy .NET. Aby dowiedzieć się więcej na temat konfigurowania projektu, w tym instalacji pakietu, dodawania using dyrektyw i tworzenia autoryzowanego obiektu klienta, zobacz Wprowadzenie do Azure Blob Storage i platformy .NET.
• Mechanizm autoryzacji musi mieć uprawnienia do wykonywania operacji przekazywania. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla następujących operacji interfejsu API REST:
  • Wstawianie obiektu blob
  • Umieść blok

Przekazywanie danych do blokowego obiektu blob

Do przekazania danych do blokowego obiektu blob można użyć jednej z następujących metod:

• Przekaż
• UploadAsync

W przypadku korzystania z tych metod przekazywania biblioteka kliencka może wywołać funkcję 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:

• OpenWrite
• OpenWriteAsync

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 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

Możesz otworzyć strumień w usłudze Blob Storage i zapisać go. Poniższy przykład tworzy plik zip w usłudze Blob Storage i zapisuje w nim pliki. Zamiast kompilowania pliku zip w pamięci lokalnej, w pamięci znajduje się tylko jeden plik.

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 z opcjami 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ć obiektów BlobUploadOptions do definiowania opcji konfiguracji podczas wywoływania metody przekazywania.

Określanie opcji transferu danych podczas przekazywania

Wartości w obszarze StorageTransferOptions można skonfigurować, 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 bycia zaleceniem. 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 Dostrajanie wydajności dla 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ą przekazywane prawidłowo i nie zostały naruszone podczas przesyłania. Opcje weryfikacji transferu można zdefiniować na poziomie klienta przy użyciu obiektów BlobClientOptions, które stosują opcje weryfikacji do wszystkich metod wywoływanych z wystąpienia obiektu BlobClient .

Możesz również zastąpić opcje walidacji transferu na poziomie metody przy użyciu obiektów 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, zgodnie z definicją storageChecksumAlgorithm:

Nazwa	Wartość	Opis
Auto	0	Zalecane. Umożliwia bibliotece wybór 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	Niestandardowe 64-bitowe 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 koń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 używanego algorytmu.

Przekazywanie przy użyciu tagów indeksu

Tagi indeksów 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 do wyszukiwania w celu łatwego znajdowania danych. Tagi można dodać do wystąpienia 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 o warstwach dostępu, zobacz Omówienie warstw dostępu.

Przekazywanie blokowego obiektu blob przez blokowe bloki 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 zostaną przygotowane, możesz zatwierdzić je 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 Azure Blob Storage dla platformy .NET, zobacz następujące zasoby.

Operacje interfejsu API REST

Zestaw Azure SDK dla platformy .NET zawiera biblioteki oparte na interfejsie API REST platformy Azure, które umożliwiają 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:

• Umieść obiekt blob (interfejs API REST)
• Umieść blok (interfejs API REST)

Przykłady kodu

• Wyświetlanie przykładów kodu z tego artykułu (GitHub)

Zobacz też

• Dostrajanie wydajności dla przekazywania i pobierania.
• Zarządzanie danymi obiektów blob platformy Azure i znajdowanie ich za pomocą tagów indeksów obiektów blob
• Używanie tagów indeksów obiektów blob do zarządzania danymi i znajdowania ich w Azure Blob Storage