Udostępnij za pośrednictwem

Pobieranie obiektu blob przy użyciu platformy .NET

  • Artykuł

W tym artykule pokazano, jak pobrać obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla platformy .NET. Dane obiektu blob można pobrać do różnych miejsc docelowych, w tym lokalną ścieżkę pliku, strumień lub ciąg tekstowy. Możesz również otworzyć strumień obiektów blob i odczytać go.

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 wykonania operacji pobierania. Aby uzyskać autoryzację przy użyciu identyfikatora Entra firmy Microsoft (zalecane), potrzebujesz wbudowanej kontroli dostępu opartej na rolach platformy Azure czytnika danych obiektów blob usługi Storage lub nowszego. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dotyczące pobierania obiektu blob (interfejsu API REST).

Pobieranie obiektu blob

Aby pobrać obiekt blob, możesz użyć dowolnej z następujących metod:

Możesz również otworzyć strumień do odczytu z obiektu blob. Strumień pobiera tylko obiekt blob, ponieważ strumień jest odczytywany. Możesz to zrobić na jeden z następujących sposobów:

Pobieranie do ścieżki pliku

Poniższy przykład pobiera obiekt blob do lokalnej ścieżki pliku. Jeśli określony katalog nie istnieje, kod zgłasza wyjątek DirectoryNotFoundException. Jeśli plik już istnieje w folderze localFilePath, jest on domyślnie zastępowany podczas kolejnych pobierania.

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

Pobieranie do strumienia

Poniższy przykład pobiera obiekt blob przez utworzenie obiektu stream , a następnie pobranie go do tego strumienia. Jeśli określony katalog nie istnieje, kod zgłasza wyjątek DirectoryNotFoundException.

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Pobieranie do ciągu

W poniższym przykładzie przyjęto założenie, że obiekt blob jest plikiem tekstowym i pobiera obiekt blob do ciągu:

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

Pobieranie ze strumienia

Poniższy przykład pobiera obiekt blob, odczytując ze strumienia:

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

Pobieranie blokowego obiektu blob z opcjami konfiguracji

Podczas pobierania obiektu blob można zdefiniować opcje konfiguracji biblioteki klienta. Te opcje można dostosować, aby zwiększyć wydajność i zwiększyć niezawodność. W poniższych przykładach kodu pokazano, jak używać obiektu BlobDownloadToOptions do definiowania opcji konfiguracji podczas wywoływania metody pobierania. Należy pamiętać, że te same opcje są dostępne dla obiektów blobDownloadOptions.

Określanie opcji transferu danych podczas pobierania

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 BlobDownloadToOptions 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 DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

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

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

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

Określanie opcji weryfikacji transferu podczas pobierania

Możesz określić opcje weryfikacji transferu, aby upewnić się, że dane są pobierane prawidłowo 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 BlobDownloadToOptions. W poniższym przykładzie kodu pokazano, jak utworzyć BlobDownloadToOptions obiekt i określić algorytm generowania sumy kontrolnej. Suma kontrolna jest następnie używana przez usługę do weryfikowania integralności danych pobranej zawartości.

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    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.

Zasoby

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

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 pobierania obiektów blob używają następującej operacji interfejsu API REST:

Przykłady kodu

Zasoby biblioteki klienta

Zobacz też