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

Из этого краткого руководства вы узнаете, как управлять большими двоичными объектами с использованием Node.js.In this quickstart, you learn to manage blobs by using Node.js. Большие двоичные объекты — это объекты, которые могут содержать большие объемы текстовых или двоичных данных, включая изображения, документы, потоковое мультимедиа и архивные данные.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 для JavaScript.This section walks you through preparing a project to work with the Azure Blob storage client library v12 for JavaScript.

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

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

  1. В окне консоли (командная строка, PowerShell или Bash) создайте каталог для проекта.In a console window (such as cmd, PowerShell, or Bash), create a new directory for the project.

    mkdir blob-quickstart-v12
    
  2. Перейдите в только что созданный каталог blob-quickstart-v12.Switch to the newly created blob-quickstart-v12 directory.

    cd blob-quickstart-v12
    
  3. Создайте текстовый файл package.json.Create a new text file called package.json. Этот файл определяет проект Node.js.This file defines the Node.js project. Сохраните этот файл в каталоге blob-quickstart-v12.Save this file in the blob-quickstart-v12 directory. Ниже приведено содержимое файла.Here is the contents of the file:

    {
        "name": "blob-quickstart-v12",
        "version": "1.0.0",
        "description": "Use the @azure/storage-blob SDK version 12 to interact with Azure Blob storage",
        "main": "blob-quickstart-v12.js",
        "scripts": {
            "start": "node blob-quickstart-v12.js"
        },
        "author": "Your Name",
        "license": "MIT",
        "dependencies": {
            "@azure/storage-blob": "^12.0.0",
            "@types/dotenv": "^4.0.3",
            "dotenv": "^6.0.0"
        }
    }
    

    Вы можете указать собственное имя в поле author, если хотите.You can put your own name in for the author field, if you'd like.

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

Оставаясь в каталоге blob-quickstart-v12, установите клиентскую библиотеку хранилища BLOB-объектов Azure для пакета JavaScript с помощью команды npm install.While still in the blob-quickstart-v12 directory, install the Azure Blob storage client library for JavaScript package by using the npm install command. Эта команда считывает файл package.json и устанавливает клиентскую библиотеку хранилища BLOB-объектов Azure версии 12 для пакета JavaScript и все библиотеки, от которых она зависит.This command reads the package.json file and installs the Azure Blob storage client library v12 for JavaScript package and all the libraries on which it depends.

npm install

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

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

  1. Откройте другой новый текстовый файл в редакторе кода.Open another new text file in your code editor

  2. Добавьте в него вызовы require для загрузки модулей Azure и Node.js.Add require calls to load Azure and Node.js modules

  3. Создайте структуру программы, включая простую обработку исключений.Create the structure for the program, including basic exception handling

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

    const { BlobServiceClient } = require('@azure/storage-blob');
    const uuidv1 = require('uuid/v1');
    
    async function main() {
        console.log('Azure Blob storage v12 - JavaScript quickstart sample');
        // Quick start code goes here
    }
    
    main().then(() => console.log('Done')).catch((ex) => console.log(ex.message));
    
  4. Сохраните новый файл как blob-quickstart-v12.js в каталоге blob-quickstart-v12.Save the new file as blob-quickstart-v12.js in the blob-quickstart-v12 directory.

Копирование учетных данных с портала 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-объектов

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

  • BlobServiceClient. Класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами больших двоичных объектов.BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers.
  • ContainerClient. Класс ContainerClient позволяет управлять контейнерами службы хранилища Azure и содержащимися в них большими двоичными объектами.ContainerClient: The ContainerClient 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.

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

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

Получение строки подключения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 function:

// 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.
const AZURE_STORAGE_CONNECTION_STRING = process.env.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.

Создайте экземпляр класса BlobServiceClient, вызвав метод fromConnectionString.Create an instance of the BlobServiceClient class by calling the fromConnectionString method. Затем вызовите метод getContainerClient, чтобы получить ссылку на контейнер.Then, call the getContainerClient method to get a reference to a container. Наконец, вызовите метод create, чтобы создать контейнер в учетной записи хранения.Finally, call create to actually create the container in your storage account.

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

// Create the BlobServiceClient object which will be used to create a container client
const blobServiceClient = BlobServiceClient.fromConnectionString(AZURE_STORAGE_CONNECTION_STRING);

// Create a unique name for the container
const containerName = 'quickstart' + uuidv1();

console.log('\nCreating container...');
console.log('\t', containerName);

// Get a reference to a container
const containerClient = blobServiceClient.getContainerClient(containerName);

// Create the container
const createContainerResponse = await containerClient.create();
console.log("Container was created successfully. requestId: ", createContainerResponse.requestId);

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

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

  1. Создает текстовую строку для передачи в большой двоичный объект.Creates a text string to upload to a blob.
  2. Получает ссылку на объект BlockBlobClient, вызывая метод getBlockBlobClient для ContainerClient из раздела Создание контейнера.Gets a reference to a BlockBlobClient object by calling the getBlockBlobClient method on the ContainerClient from the Create a container section.
  3. Передает данные текстовой строки в большой двоичный объект, вызывая метод upload.Uploads the text string data to the blob by calling the upload method.

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

// Create a unique name for the blob
const blobName = 'quickstart' + uuidv1() + '.txt';

// Get a block blob client
const blockBlobClient = containerClient.getBlockBlobClient(blobName);

console.log('\nUploading to Azure storage as blob:\n\t', blobName);

// Upload data to the blob
const data = 'Hello, World!';
const uploadBlobResponse = await blockBlobClient.upload(data, data.length);
console.log("Blob was uploaded successfully. requestId: ", uploadBlobResponse.requestId);

Перечисление BLOB-объектов в контейнереList the blobs in a container

Выведите список больших двоичных объектов в контейнере, вызвав метод listBlobsFlat.List the blobs in the container by calling the listBlobsFlat 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 function:

console.log('\nListing blobs...');

// List the blob(s) in the container.
for await (const blob of containerClient.listBlobsFlat()) {
    console.log('\t', blob.name);
}

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

Скачайте созданный ранее большой двоичный объект, вызвав метод download.Download the previously created blob by calling the download method. В примере кода есть вспомогательная функция streamToString, которая используется для считывания потока Node.js в строку.The example code includes a helper function called streamToString, which is used to read a Node.js readable stream into a string.

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

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blockBlobClient.download(0);
console.log('\nDownloaded blob content...');
console.log('\t', await streamToString(downloadBlockBlobResponse.readableStreamBody));

Добавьте эту вспомогательную функцию после функции main.Add this helper function after the main function:

// A helper function used to read a Node.js readable stream into a string
async function streamToString(readableStream) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readableStream.on("data", (data) => {
      chunks.push(data.toString());
    });
    readableStream.on("end", () => {
      resolve(chunks.join(""));
    });
    readableStream.on("error", reject);
  });
}

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

Следующий код очищает созданные приложением ресурсы, полностью удаляя контейнер с помощью метода delete.The following code cleans up the resources the app created by removing the entire container using the delete method. Кроме того, при необходимости можно удалить локальные файлы.You can also delete the local files, if you like.

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

console.log('\nDeleting container...');

// Delete container
const deleteContainerResponse = await containerClient.delete();
console.log("Container was deleted successfully. requestId: ", deleteContainerResponse.requestId);

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

Это приложение создает текстовую строку и передает ее в хранилище BLOB-объектов.This app creates a text string and uploads it to Blob storage. Затем пример выводит список больших двоичных объектов в контейнере, скачивает большой двоичный объект и отображает скачанные данные.The example then lists the blob(s) in the container, downloads the blob, and displays the downloaded data.

В окне консоли перейдите в каталог, содержащий файл blob-quickstart-v12.py, а затем выполните указанную команду node, чтобы запустить приложение.From a console prompt, navigate to the directory containing the blob-quickstart-v12.py file, then execute the following node command to run the app.

node blob-quickstart-v12.js

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

Azure Blob storage v12 - JavaScript quickstart sample

Creating container...
         quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
         quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
         quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
         Hello, World!

Deleting container...
Done

Пошагово выполните код в отладчике и просматривайте результаты на портале Azure.Step through the code in your debugger and check your Azure portal throughout the process. Проверьте, создан ли контейнер.Check to see that the container is being created. Вы можете открыть большой двоичный объект в контейнере и просмотреть его содержимое.You can open the blob inside the container and view the contents.

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

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

Учебники, примеры, краткие руководства и другую документацию можно найти по следующим ссылкам:For tutorials, samples, quickstarts, and other documentation, visit: