Краткое руководство. Управление большими двоичными объектами с помощью пакета SDK для Java версии 12

Из этого краткого руководства вы узнаете, как управлять большими двоичными объектами с использованием Java. Большие двоичные объекты — это объекты, которые могут содержать большие объемы текстовых или двоичных данных, включая изображения, документы, потоковое мультимедиа и архивные данные. Вы научитесь отправлять и скачивать большие двоичные объекты, получать список таких объектов, а также создавать и удалять контейнеры.

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

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

Настройка

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

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

Создайте приложение Java с именем blob-quickstart-v12.

  1. В окне консоли (командная строка, PowerShell или Bash) с помощью Maven создайте консольное приложение с именем blob-quickstart-v12. Введите следующую команду mvn, чтобы создать проект Java "Hello World".

    mvn archetype:generate `
        --define interactiveMode=n `
        --define groupId=com.blobs.quickstart `
        --define artifactId=blob-quickstart-v12 `
        --define archetypeArtifactId=maven-archetype-quickstart `
        --define archetypeVersion=1.4
    
  2. Примерный результат создания проекта показан ниже.

    [INFO] Scanning for projects...
    [INFO]
    [INFO] ------------------< org.apache.maven:standalone-pom >-------------------
    [INFO] Building Maven Stub Project (No POM) 1
    [INFO] --------------------------------[ pom ]---------------------------------
    [INFO]
    [INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
    [INFO]
    [INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
    [INFO]
    [INFO]
    [INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
    [INFO] Generating project in Batch mode
    [INFO] ----------------------------------------------------------------------------
    [INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
    [INFO] ----------------------------------------------------------------------------
    [INFO] Parameter: groupId, Value: com.blobs.quickstart
    [INFO] Parameter: artifactId, Value: blob-quickstart-v12
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.blobs.quickstart
    [INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.blobs.quickstart
    [INFO] Parameter: groupId, Value: com.blobs.quickstart
    [INFO] Parameter: artifactId, Value: blob-quickstart-v12
    [INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart-v12
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  7.056 s
    [INFO] Finished at: 2019-10-23T11:09:21-07:00
    [INFO] ------------------------------------------------------------------------
        ```
    
    
  3. Switch to the newly created blob-quickstart-v12 folder.

    cd blob-quickstart-v12
    
  4. В каталоге blob-quickstart-v12 создайте каталог data. Это каталог для создания и хранения файлов данных больших двоичных объектов.

    mkdir data
    

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

Откройте файл pom.xml в текстовом редакторе. Добавьте приведенный ниже элемент зависимости в группу зависимостей.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.13.0</version>
</dependency>

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

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

  1. Перейдите в каталог /src/main/java/com/blobs/quickstart.
  2. Откройте файл App.java в редакторе.
  3. Удалите оператор System.out.println("Hello world!");.
  4. Добавьте директивы import.

Вот этот код:

package com.blobs.quickstart;

/**
 * Azure blob storage v12 SDK quickstart
 */
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
    }
}

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

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

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

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

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

    Снимок экрана: местоположение параметров ключа доступа в портал Azure

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

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

    Снимок экрана, на котором показано, как скопировать строку подключения с портала Azure

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

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

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

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

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

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

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

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

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

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

Схема архитектуры службы хранилища BLOB-объектов

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

  • BlobServiceClient. Класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами больших двоичных объектов. Учетная запись хранения предоставляет пространство имен верхнего уровня для службы BLOB-объектов.
  • Класс предоставляет API гибкого конструктора для упрощения настройки и создания экземпляров объектов .
  • BlobContainerClient. Класс BlobContainerClient позволяет управлять контейнерами службы хранилища Azure и содержащимися в них большими двоичными объектами.
  • Класс [ позволяет управлять большими двоичными объектами службы хранилища Azure.
  • BlobItem. Класс BlobItem представляет отдельные большие двоичные объекты, возвращаемые при вызове метода listBlobs.

Примеры кода

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

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

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

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

System.out.println("Azure Blob Storage v12 - Java 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 connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");

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

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

Важно!

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

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

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

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

//Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

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

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

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

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

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

// Create a local file in the ./data/ directory for uploading and downloading
String localPath = "./data/";
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";
File localFile = new File(localPath + fileName);

// Write text to the file
FileWriter writer = new FileWriter(localPath + fileName, true);
writer.write("Hello, World!");
writer.close();

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

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

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

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

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

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : containerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

Скачивание больших двоичных объектов

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

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

// Download the blob to a local file
// Append the string "DOWNLOAD" before the .txt extension so that you can see both files.
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");
File downloadedFile = new File(localPath + downloadFileName);

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

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

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

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

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

// Clean up
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
containerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

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

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

Перейдите в каталог, содержащий файл pom.xml, и скомпилируйте проект с помощью следующей команды mvn.

mvn compile

Затем выполните сборку пакета.

mvn package

Выполните следующую команду mvn для запуска приложения.

mvn exec:java -Dexec.mainClass="com.blobs.quickstart.App" -Dexec.cleanupDaemonThreads=false

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

Azure Blob Storage v12 - Java quickstart sample

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsf9aa68a5-260e-47e6-bea2-2dcfcfa1fd9a/quickstarta9c3a53e-ae9d-4863-8b34-f3d807992d65.txt

Listing blobs...
        quickstarta9c3a53e-ae9d-4863-8b34-f3d807992d65.txt

Downloading blob to
        ./data/quickstarta9c3a53e-ae9d-4863-8b34-f3d807992d65DOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

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

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

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

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

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