Краткое руководство. Использование библиотеки Хранилища BLOB-объектов Azure версии 12 для .NET

Приступите к работе с клиентской библиотекой Хранилища BLOB-объектов Azure версии 12 для .NET. Хранилище BLOB-объектов Azure — это решение корпорации Майкрософт для хранения объектов в облаке. Чтобы установить пакет и испробовать пример кода для выполнения базовых задач, выполните приведенные здесь действия. Хранилище BLOB-объектов оптимизировано для хранения больших объемов неструктурированных данных.

В примерах этого краткого руководства показано, как использовать клиентскую библиотеку Хранилища BLOB-объектов Azure для .NET версии 12 для выполнения следующих задач:

• Получение строки подключения
• Создание контейнера
• Отправка большого двоичного объекта в контейнер
• Получение списка BLOB-объектов в контейнере
• Скачивание большого двоичного объекта
• Удаление контейнера

Дополнительные ресурсы:

• Справочная документация по API
• Исходный код библиотеки
• Пакет (NuGet)
• Примеры

Предварительные требования

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Пакет SDK для .NET Core последней версии для вашей операционной системы. Обязательно получите пакет SDK, а не среду выполнения.

Настройка

В этом разделе рассматривается подготовка проекта для работы с клиентской библиотекой Хранилища BLOB-объектов Azure версии 12 для .NET.

Создание проекта

Создайте приложение .NET Core с именем BlobQuickstartV12.

1. В окне консоли (командная строка, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение BlobQuickstartV12. Эта команда создает простой проект Hello World на языке C# с одним файлом исходного кода: Program.cs.

   dotnet new console -n BlobQuickstartV12
   

2. Переключитесь на только что созданный каталог BlobQuickstartV12.

   cd BlobQuickstartV12
   

3. В каталоге BlobQuickstartV12 создайте каталог data. Это каталог для создания и хранения файлов данных больших двоичных объектов.

   mkdir data
   

Установка пакета

Оставаясь в каталоге приложения, установите клиентскую библиотеку хранилища BLOB-объектов Azure для пакета .NET с помощью команды dotnet add package.

dotnet add package Azure.Storage.Blobs

Настройка платформы приложения

Из каталога проекта:

1. Откройте файл Program.cs в редакторе.

2. Удалите оператор Console.WriteLine("Hello World!"); .

3. Добавьте директивы using.

4. Обновите объявление метода Main, чтобы он поддерживал асинхронное выполнение.

   Вот этот код:

   using Azure.Storage.Blobs;
   using Azure.Storage.Blobs.Models;
   using System;
   using System.IO;
   using System.Threading.Tasks;
   
   namespace BlobQuickstartV12
   {
       class Program
       {
           static async Task Main()
           {
           }
       }
   }
   

Копирование учетных данных с портала Azure

Когда пример приложения выполняет запрос к службе хранилища Azure, он должен быть авторизован. Для авторизации запроса добавьте в приложение учетные данные учетной записи хранения в виде строки подключения. Чтобы просмотреть учетные данные учетной записи хранения, выполните следующие шаги:

1. Войдите на портал Azure.

2. Перейдите к учетной записи хранения.

3. На панели меню учетной записи хранения в разделе Безопасность и сети выберите Ключи доступа. На этой странице вы увидите ключи доступа к учетной записи и полную строку подключения для каждого ключа.

   

4. В области Ключи доступа выберите команду Показать ключи.

5. В разделе key1 выберите значение Строка подключения. Нажмите значок Копировать в буфер обмена, чтобы скопировать строку подключения. В следующем разделе вы добавите значение строки подключения в переменную среды.

   

Настройка строки подключения хранилища

После копирования строки подключения запишите ее в переменной среды на локальном компьютере, где выполняется приложение. Чтобы задать переменную среды, откройте окно консоли и следуйте инструкциям для используемой операционной системы. Замените <yourconnectionstring> фактической строкой подключения.

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Linux и macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

После добавления переменной среды в Windows вам необходимо запустить новый экземпляр командного окна.

Перезапуск программ

После добавления переменной среды перезапустите все запущенные программы, которым может понадобиться считать переменную среды. Например, перезапустите среду разработки или редактор, прежде чем продолжить.

Объектная модель

Хранилище BLOB-объектов Azure оптимизировано для хранения больших объемов неструктурированных данных. Неструктурированные данные — это данные, которые не соответствуют определенной модели данных или определению, например текстовых или двоичных данных. В хранилище BLOB-объектов предлагается три типа ресурсов:

• учетная запись хранения;
• контейнер в учетной записи хранения;
• большой двоичный объект в контейнере.

На следующей схеме показана связь между этими ресурсами.

Используйте следующие классы .NET для взаимодействия с этими ресурсами:

• BlobServiceClient. Класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами больших двоичных объектов.
• BlobContainerClient. Класс BlobContainerClient позволяет управлять контейнерами службы хранилища Azure и содержащимися в них большими двоичными объектами.
• BlobClient. Класс BlobClient позволяет управлять большими двоичными объектами службы хранилища Azure.

Примеры кода

Фрагменты кода в следующих разделах демонстрируют, как выполнять основные операции с данными с помощью клиентской библиотеки Хранилища BLOB-объектов Azure для .NET.

Получение строки подключения

Приведенный ниже код извлекает строку подключения для учетной записи хранения из переменной среды, созданной в разделе Настройка строки подключения хранилища.

Добавьте этот код в метод Main.

Console.WriteLine("Azure Blob Storage v12 - .NET quickstart sample\n");

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the
// environment variable is created after the application is launched in a
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

Создание контейнера

Выберите имя нового контейнера. Приведенный ниже код добавляет к имени контейнера значение GUID, чтобы сделать это имя уникальным.

Важно!

Имена контейнеров должны состоять из знаков нижнего регистра. Дополнительные сведения об именовании контейнеров и больших двоичных объектов см. в статье Naming and Referencing Containers, Blobs, and Metadata (Именование контейнеров, больших двоичных объектов и метаданных и ссылка на них).

Создайте экземпляр класса BlobServiceClient. Затем вызовите метод CreateBlobContainerAsync, чтобы создать контейнер в своей учетной записи хранения.

Добавьте следующий код в конец метода Main.

// Create a BlobServiceClient object which will be used to create a container client
BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Отправка большого двоичного объекта в контейнер

Приведенный ниже фрагмент кода:

1. Создает текстовый файл в локальном каталоге data.
2. Возвращает ссылку на объект BlobClient, вызывая метод GetBlobClient для контейнера из раздела Создание контейнера.
3. Передает локальный текстовый файл в большой двоичный объект, вызывая метод UploadAsync. С помощью этого метода создается большой двоичный объект, если он не был создан ранее, или же, если он имеется, происходит его замещение.

Добавьте следующий код в конец метода Main.

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "./data/";
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Получение списка BLOB-объектов в контейнере

Выведите список больших двоичных объектов в контейнере, вызвав метод GetBlobsAsync. В этом случае в контейнер был добавлен лишь один большой двоичный объект, поэтому операция перечисления возвращает только его.

Добавьте следующий код в конец метода Main.

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Загрузка больших двоичных объектов

Скачайте созданный ранее BLOB-объект, вызвав метод DownloadToAsync. Пример кода добавляет суффикс "DOWNLOADED" к имени файла, чтобы в локальной файловой системе можно было просмотреть оба файла.

Добавьте следующий код в конец метода Main.

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Удаление контейнера

Следующий код очищает созданные приложением ресурсы, полностью удаляя контейнер с помощью метода DeleteAsync. Он также удаляет локальные файлы, созданные приложением.

Приложение приостанавливается для ввода пользователя, вызывая Console.ReadLine, перед удалением большого двоичного объекта, контейнера и локальных файлов. Это хорошая возможность проверить правильность создания ресурсов перед их удалением.

Добавьте следующий код в конец метода Main.

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Выполнение кода

В этом приложении тестовый файл создается в локальной папке data, а затем передается в хранилище BLOB-объектов. После этого выводится список больших двоичных объектов в контейнере, а затем файл загружается с новым именем, чтобы можно было сравнить старый и новый файлы.

Перейдите к каталогу приложения, выполните его сборку и запустите его.

dotnet build

dotnet run

Вы должны увидеть выходные данные приложения, как показано ниже.

Azure Blob Storage v12 - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Прежде чем начать удаление, проверьте наличие двух файлов в папке data. Вы можете открыть их и убедиться, что они идентичны.

После проверки файлов нажмите клавишу ВВОД, чтобы завершить работу с демонстрационной версией и удалить тестовые файлы.

Дальнейшие действия

В этом кратком руководстве вы узнали, как передавать, загружать и перечислять файлы в большие двоичные объекты с помощью .NET.

Чтобы просмотреть примеры приложений для хранилища BLOB-объектов, перейдите к следующему разделу:

Примеры для пакета SDK Хранилища BLOB-объектов Azure версии 12 для .NET

• Руководства, примеры, краткие руководства и другую документацию можно найти на странице Azure для разработчиков .NET и .NET Core.
• Дополнительные сведения о .NET Core см. в статье Get started with .NET in 10 minutes (Быстрое начало работы с .NET).