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

Из этого краткого руководства вы узнаете, как управлять большими двоичными объектами с использованием Java.In this quickstart, you learn to manage blobs by using Java. Большие двоичные объекты — это объекты, которые могут содержать большие объемы текстовых или двоичных данных, включая изображения, документы, потоковое мультимедиа и архивные данные.Blobs are objects that can hold large amounts of text or binary data, including images, documents, streaming media, and archive data. Вы научитесь отправлять и скачивать большие двоичные объекты, получать список таких объектов, а также создавать и удалять контейнеры.You'll upload, download, and list blobs, and you'll create and delete containers.

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

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

Примечание

Функции, описанные в этой статье, теперь доступны для учетных записей с иерархическим пространством имен.The features described in this article are now available to accounts that have a hierarchical namespace. Чтобы просмотреть ограничения, ознакомьтесь с возможностями хранилища BLOB-объектов, доступными в Azure Data Lake Storage 2-го поколения статье.To review limitations, see the Blob storage features available in Azure Data Lake Storage Gen2 article.

НастройкаSetting up

В этом разделе рассматривается подготовка проекта для работы с клиентской библиотекой хранилища BLOB-объектов Azure версии 12 для Java.This section walks you through preparing a project to work with the Azure Blob storage client library v12 for Java.

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

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

  1. В окне консоли (командная строка, PowerShell или Bash) с помощью Maven создайте консольное приложение с именем blob-quickstart-v12.In a console window (such as cmd, PowerShell, or Bash), use Maven to create a new console app with the name blob-quickstart-v12. Введите следующую команду mvn, чтобы создатьType the following mvn command to create a "Hello world!" проект Java "Hello World".Java project.

    mvn archetype:generate -DgroupId=com.blobs.quickstart \
                           -DartifactId=blob-quickstart-v12 \
                           -DarchetypeArtifactId=maven-archetype-quickstart \
                           -DarchetypeVersion=1.4 \
                           -DinteractiveMode=false
    
  2. Примерный результат создания проекта показан ниже.The output from generating the project should look something like this:

    [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.In side the blob-quickstart-v12 directory, create another directory called data. Это каталог для создания и хранения файлов данных больших двоичных объектов.This is where the blob data files will be created and stored.

    mkdir data
    

Установка пакетаInstall the package

Откройте файл pom.xml в текстовом редакторе.Open the pom.xml file in your text editor. Добавьте приведенный ниже элемент зависимости в группу зависимостей.Add the following dependency element to the group of dependencies.

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

Настройка платформы приложенияSet up the app framework

Из каталога проекта:From the project directory:

  1. Перейдите в каталог /src/main/java/com/blobs/quickstart.Navigate to the /src/main/java/com/blobs/quickstart directory
  2. Откройте файл App.java в редакторе.Open the App.java file in your editor
  3. Удалите оператор System.out.println("Hello world!");.Delete the System.out.println("Hello world!"); statement
  4. Добавьте директивы import.Add import directives

Вот этот код:Here's the code:

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

Копирование учетных данных с портала AzureCopy your credentials from the Azure portal

Когда пример приложения выполняет запрос к службе хранилища Azure, он должен быть авторизован.When the sample application makes a request to Azure Storage, it must be authorized. Для авторизации запроса добавьте в приложение учетные данные учетной записи хранения в виде строки подключения.To authorize a request, add your storage account credentials to the application as a connection string. Чтобы просмотреть учетные данные учетной записи хранения, выполните следующие действия:View your storage account credentials by following these steps:

  1. Войдите на портал Azure.Sign in to the Azure portal.

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

  3. В разделе Параметры учетной записи хранения выберите параметр Ключи доступа.In the Settings section of the storage account overview, select Access keys. На этой странице вы увидите ключи доступа к учетной записи и полную строку подключения для каждого ключа.Here, you can view your account access keys and the complete connection string for each key.

  4. Найдите значение для параметра Строка подключения в разделе Key1 и нажмите кнопку Скопировать, чтобы скопировать строку подключения.Find the Connection string value under key1, and select the Copy button to copy the connection string. На следующем этапе вы добавите значение строки подключения в переменную среды.You will add the connection string value to an environment variable in the next step.

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

Настройка строки подключения хранилищаConfigure your storage connection string

После копирования строки подключения запишите ее в переменной среды на локальном компьютере, где выполняется приложение.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Чтобы задать переменную среды, откройте окно консоли и следуйте инструкциям для используемой операционной системы.To set the environment variable, open a console window, and follow the instructions for your operating system. Замените <yourconnectionstring> фактической строкой подключения.Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

После добавления переменной среды в Windows вам необходимо запустить новый экземпляр командного окна.After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSmacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

После добавления переменной среды перезапустите все запущенные программы, которым может понадобиться считать переменную среды.After you add the environment variable, restart any running programs that will need to read the environment variable. Например, перезапустите среду разработки или редактор, прежде чем продолжить.For example, restart your development environment or editor before continuing.

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

Хранилище BLOB-объектов Azure оптимизировано для хранения больших объемов неструктурированных данных.Azure Blob storage is optimized for storing massive amounts of unstructured data. Неструктурированные данные — это данные, которые не соответствуют определенной модели данных или определению, например текстовых или двоичных данных.Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. В хранилище BLOB-объектов предлагается три типа ресурсов:Blob storage offers three types of resources:

  • учетная запись хранения;The storage account
  • контейнер в учетной записи хранения;A container in the storage account
  • большой двоичный объект в контейнере.A blob in the container

На следующей схеме показана связь между этими ресурсами.The following diagram shows the relationship between these resources.

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

Используйте следующие классы Java для взаимодействия с этими ресурсами.Use the following Java classes to interact with these resources:

  • BlobServiceClient. Класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами больших двоичных объектов.BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers. Учетная запись хранения предоставляет пространство имен верхнего уровня для службы BLOB-объектов.The storage account provides the top-level namespace for the Blob service.
  • BlobServiceClientBuilder. Класс BlobServiceClientBuilder предоставляет API гибкого конструктора для упрощения настройки и создания экземпляров объектов BlobServiceClient.BlobServiceClientBuilder: The BlobServiceClientBuilder class provides a fluent builder API to help aid the configuration and instantiation of BlobServiceClient objects.
  • BlobContainerClient. Класс BlobContainerClient позволяет управлять контейнерами службы хранилища Azure и содержащимися в них большими двоичными объектами.BlobContainerClient: The BlobContainerClient class allows you to manipulate Azure Storage containers and their blobs.
  • BlobClient. Класс BlobClient позволяет управлять большими двоичными объектами службы хранилища Azure.BlobClient: The BlobClient class allows you to manipulate Azure Storage blobs.
  • BlobItem. Класс BlobItem представляет отдельные большие двоичные объекты, возвращаемые при вызове listBlobsFlat.BlobItem: The BlobItem class represents individual blobs returned from a call to listBlobsFlat.

Примеры кодаCode examples

В этих примерах фрагментов кода показано, как выполнять следующие действия с помощью клиентской библиотеки хранилища BLOB-объектов Azure для Java:These example code snippets show you how to perform the following with the Azure Blob storage client library for Java:

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

Приведенный ниже код извлекает строку подключения для учетной записи хранения из переменной среды, созданной в разделе Настройка строки подключения хранилища.The code below retrieves the connection string for the storage account from the environment variable created in the Configure your storage connection string section.

Добавьте этот код в метод Main.Add this code inside the Main method:

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

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

Выберите имя нового контейнера.Decide on a name for the new container. Приведенный ниже код добавляет к имени контейнера значение UUID, чтобы сделать это имя уникальным.The code below appends a UUID value to the container name to ensure that it is unique.

Важно!

Имена контейнеров должны состоять из знаков нижнего регистра.Container names must be lowercase. Дополнительные сведения об именовании контейнеров и больших двоичных объектов см. в статье Naming and Referencing Containers, Blobs, and Metadata (Именование контейнеров, больших двоичных объектов и метаданных и ссылка на них).For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

Затем создайте экземпляр класса BlobContainerClient и вызовите метод create, чтобы создать контейнер в учетной записи хранения.Next, create an instance of the BlobContainerClient class, then call the create method to actually create the container in your storage account.

Добавьте следующий код в конец метода Main.Add this code to the end of the Main method:

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

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

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

  1. Создает текстовый файл в локальном каталоге data.Creates a text file in the local data directory.
  2. Возвращает ссылку на объект BlobClient, вызывая метод getBlobClient для контейнера из раздела Создание контейнера.Gets a reference to a BlobClient object by calling the getBlobClient method on the container from the Create a container section.
  3. Передает локальный текстовый файл в большой двоичный объект, вызывая метод uploadFromFile.Uploads the local text file to the blob by calling the uploadFromFile method. С помощью этого метода создается большой двоичный объект, если он не был создан ранее. Если он имеется, замещение не происходит.This method creates the blob if it doesn't already exist, but will not overwrite it if it does.

Добавьте следующий код в конец метода Main.Add this code to the end of the Main method:

// 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-объектов в контейнереList the blobs in a container

Выведите список больших двоичных объектов в контейнере, вызвав метод listBlobs.List the blobs in the container by calling the listBlobs method. В этом случае в контейнер был добавлен лишь один большой двоичный объект, поэтому операция перечисления возвращает только его.In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

Добавьте следующий код в конец метода Main.Add this code to the end of the Main method:

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

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

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

Скачайте созданный ранее большой двоичный объект, вызвав метод downloadToFile.Download the previously created blob by calling the downloadToFile method. Пример кода добавляет суффикс "DOWNLOAD" к имени файла, чтобы в локальной файловой системе можно было просмотреть оба файла.The example code adds a suffix of "DOWNLOAD" to the file name so that you can see both files in local file system.

Добавьте следующий код в конец метода Main.Add this code to the end of the Main method:

// 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 a container

Следующий код очищает созданные приложением ресурсы, полностью удаляя контейнер с помощью метода delete.The following code cleans up the resources the app created by removing the entire container using the delete method. Он также удаляет локальные файлы, созданные приложением.It also deletes the local files created by the app.

Приложение приостанавливается для ввода пользователя, вызывая System.console().readLine(), перед удалением большого двоичного объекта, контейнера и локальных файлов.The app pauses for user input by calling System.console().readLine() before it deletes the blob, container, and local files. Это хорошая возможность проверить правильность создания ресурсов перед их удалением.This is a good chance to verify that the resources were created correctly, before they are deleted.

Добавьте следующий код в конец метода Main.Add this code to the end of the Main method:

// 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");

Выполнение кодаRun the code

В этом приложении тестовый файл создается в локальной папке, а затем передается в хранилище BLOB-объектов.This app creates a test file in your local folder and uploads it to Blob storage. После этого выводится список больших двоичных объектов в контейнере, а затем файл загружается с новым именем, чтобы можно было сравнить старый и новый файлы.The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.

Перейдите в каталог, содержащий файл pom.xml, и скомпилируйте проект с помощью следующей команды mvn.Navigate to the directory containing the pom.xml file and compile the project by using the following mvn command.

mvn compile

Затем выполните сборку пакета.Then, build the package.

mvn package

Выполните следующую команду mvn для запуска приложения.Run the following mvn command to execute the app.

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

Вы должны увидеть выходные данные приложения, как показано ниже.The output of the app is similar to the following example:

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.Before you begin the clean up process, check your data folder for the two files. Вы можете открыть их и убедиться, что они идентичны.You can open them and observe that they are identical.

После проверки файлов нажмите клавишу ВВОД, чтобы завершить работу с демонстрационной версией и удалить тестовые файлы.After you've verified the files, press the Enter key to delete the test files and finish the demo.

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

В этом кратком руководстве вы узнали, как передавать и скачивать большие двоичные объекты, а также выводить их список с помощью Java.In this quickstart, you learned how to upload, download, and list blobs using Java.

Чтобы просмотреть примеры приложений для хранилища BLOB-объектов, перейдите к следующему разделу:To see Blob storage sample apps, continue to: