Клиентская библиотека BLOB-объектов службы хранилища Azure для JavaScript — версия 12.28.0

2025-07-24

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

Этот проект предоставляет клиентскую библиотеку в JavaScript, которая упрощает использование службы BLOB-объектов службы хранилища Microsoft Azure.

Используйте клиентские библиотеки в этом пакете, чтобы:

Получение и задание свойств службы BLOB-объектов
Create/List/Delete Containers
Создание,чтение/список/обновление/удаление blob-объектов блоков
Создание,чтение/список/обновление/удаление страничных BLOB-объектов
Создание,чтение/список/обновление/удаление больших двоичных объектов

Key links

Source code
Package (npm)
Справочная документация по API
Product documentation
Samples
REST API хранилища Azure

Getting started

Поддерживаемые в настоящее время среды

LTS версии Node.js
Последние версии Safari, Chrome, Edge и Firefox.

See our support policy for more details.

Prerequisites

An Azure subscription
A Storage Account

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

Предпочтительный способ установки клиентской библиотеки BLOB-объектов службы хранилища Azure для JavaScript — использовать диспетчер пакетов npm. Введите следующее в окно терминала:

npm install @azure/storage-blob

Проверка подлинности клиента

Служба хранилища Azure поддерживает несколько способов проверки подлинности. Чтобы взаимодействовать со службой хранилища BLOB-объектов Azure, необходимо создать экземпляр клиента хранилища — BlobServiceClient, ContainerClientили BlobClient, например. Дополнительные сведения о проверке подлинности см. в примерах для создания BlobServiceClient.

Azure Active Directory
Shared Key
подписей общего доступа

Azure Active Directory

Служба хранилища BLOB-объектов Azure поддерживает использование Azure Active Directory для проверки подлинности запросов к своим API. Пакет @azure/identity предоставляет различные типы учетных данных, которые приложение может использовать для этого. Чтобы приступить к работе, ознакомьтесь с README для @azure/identity получения дополнительных сведений и примеров.

Compatibility

Эта библиотека совместима с Node.js и браузерами и проверена на основе версий LTS Node.js (>=8.16.0) и последних версий Chrome, Firefox и Edge.

Web Workers

Эта библиотека требует, чтобы некоторые объекты DOM были глобально доступны при использовании в браузере, которые веб-работники по умолчанию не делают доступными. Эти библиотеки необходимо заполнить, чтобы эта библиотека работала в веб-рабочих нагрузках.

Дополнительные сведения см. в нашей документации по использованию пакета SDK Azure для JS в веб-рабочих

Эта библиотека зависит от следующих API-интерфейсов DOM, которые нуждаются во внешних полизаполнениях, загруженных при использовании в веб-рабочих нагрузках:

Различия между Node.js и браузерами

Существуют различия между средой выполнения Node.js и браузерами. При начале работы с этой библиотекой обратите внимание на API-интерфейсы или классы, помеченные "ТОЛЬКО ДОСТУПНО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS" или "ТОЛЬКО ДОСТУПНЫ В БРАУЗЕРАХ".

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

Функции, интерфейсы, классы или функции, доступные только в Node.js

Авторизация общего ключа на основе имени учетной записи и ключа учетной записи
- StorageSharedKeyCredential
Создание подписанного URL-адреса (SAS)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Параллельная отправка и скачивание. Обратите внимание, что BlockBlobClient.uploadData() доступна как в Node.js, так и в браузерах.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Функции, интерфейсы, классы или функции, доступные только в браузерах

Параллельная отправка и скачивание
- BlockBlobClient.uploadBrowserData()

JavaScript Bundle

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. For details on how to do this, please refer to our bundling documentation.

CORS

Необходимо настроить правила совместного использования ресурсов (CORS) для учетной записи хранения, если необходимо разработать для браузеров. Перейдите на портал Azure и обозреватель службы хранилища Azure, найдите свою учетную запись хранения, создайте новые правила CORS для больших двоичных объектов, очередей, файлов и таблиц.

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

Допустимые источники: *
Разрешенные команды: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Разрешенные заголовки: *
Открытые заголовки: *
Максимальный возраст (в секундах): 86400

Key concepts

Хранилище BLOB-объектов предназначено для:

Обслуживание изображений или документов непосредственно в браузере.
Хранение файлов для распределенного доступа.
Потоковая передача видео и звука.
Запись в файлы журнала.
Хранение данных для резервного копирования и восстановления, аварийного восстановления и архивации.
Хранение данных для анализа локальной или размещенной в Azure службе.

Хранилище BLOB-объектов предлагает три типа ресурсов:

The storage account used via BlobServiceClient
A container in the storage account used via ContainerClient
A blob in a container used via BlobClient

Examples

Импорт пакета
Создание клиента службы BLOB-объектов
создание нового контейнера
Перечисление контейнеров
Создание большого двоичного объекта путем отправки данных
список БОЛЬШИХ двоичных объектов в контейнере
Скачайте большой двоичный объект и преобразуйте его в строку (Node.js)
Скачайте большой двоичный объект и преобразуйте его в строку (браузеры)

Импорт пакета

Чтобы использовать клиенты, импортируйте пакет в файл:

import * as AzureStorageBlob from "@azure/storage-blob";

Кроме того, выборочно импортируйте только необходимые типы:

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

Создание клиента службы BLOB-объектов

Для BlobServiceClient требуется URL-адрес службы BLOB-объектов и учетные данные доступа. Он также при необходимости принимает некоторые параметры в параметре options.

с `DefaultAzureCredential` из пакета `@azure/identity`

Рекомендуемый способ создания экземпляра BlobServiceClient

Настройка: Справочник — авторизация доступа к большим двоичным объектам и очередям с помощью Azure Active Directory из клиентского приложения — https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

Регистрация нового приложения AAD и предоставление разрешений на доступ к службе хранилища Azure от имени вошедшего пользователя
- Зарегистрируйте новое приложение в Azure Active Directory(в azure-portal) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- В разделе API permissions выберите Add a permission и выберите Microsoft APIs.
- Выберите Azure Storage и установите флажок рядом с user_impersonation и щелкните Add permissions. Это позволит приложению получить доступ к службе хранилища Azure от имени вошедшего пользователя.
Предоставление доступа к данным BLOB-объектов Azure с помощью RBAC на портале Azure
- Роли RBAC для больших двоичных объектов и очередей - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- На портале Azure перейдите к учетной записи хранения и назначьте участнику данных BLOB-объектов хранилища роль зарегистрированного приложения AAD на вкладке Access control (IAM) (на левой панели навигации учетной записи хранения на портале Azure).
Настройка среды для примера
- На странице обзора приложения AAD запишите CLIENT ID и TENANT ID. На вкладке "Сертификаты & секреты" создайте секрет и запишите это вниз.
- Убедитесь, что у вас есть AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET в качестве переменных среды для успешного выполнения примера (может использовать process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential,
);

Полный пример проверки подлинности Azure AD см. в примера проверки подлинности Azure AD.

[Примечание. Приведенные выше шаги предназначены только для Node.js]

использование строки подключения

Кроме того, можно создать экземпляр BlobServiceClient с помощью статического метода fromConnectionString() с полной строкой подключения в качестве аргумента. (Строка подключения может быть получена на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

с `StorageSharedKeyCredential`

Кроме того, вы создаете экземпляр BlobServiceClient с StorageSharedKeyCredential путем передачи имени учетной записи и ключа учетной записи в качестве аргументов. (Имя учетной записи и ключ учетной записи можно получить на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential,
);

с маркером SAS

Кроме того, можно создать экземпляр BlobServiceClient с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure или создать его с помощью generateAccountSASQueryParameters().

import { BlobServiceClient } from "@azure/storage-blob";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net?${sas}`);

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

Используйте BlobServiceClient.getContainerClient() для получения экземпляра клиента контейнера, а затем создайте новый ресурс контейнера.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);

Вывод списка контейнеров

Используйте функцию BlobServiceClient.listContainers() для итерации контейнеров с новым синтаксисом for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

Кроме того, без использования for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

Кроме того, для перечисления также поддерживается разбиение на страницы с помощью byPage():

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

For a complete sample on iterating containers please see samples/v12/typescript/src/listContainers.ts.

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

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

Аналогично перечислению контейнеров.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

For a complete sample on iterating blobs please see samples/v12/typescript/src/listBlobsFlat.ts.

Скачайте большой двоичный объект и преобразуйте его в строку (Node.js)

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

Скачайте большой двоичный объект и преобразуйте его в строку (браузеры).

Please refer to the JavaScript Bundle section for more information on using this library in the browser.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

A complete example of simple scenarios is at samples/v12/typescript/src/sharedKeyAuth.ts.

Troubleshooting

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Next steps

Дополнительные примеры кода:

примеры хранилища BLOB-объектов (JavaScript)
примеры хранилища BLOB-объектов (TypeScript)
тестовые случаи хранилища BLOB-объектов

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

Дополнительные сведения о настройке тестовой среды для библиотек хранилища см. в руководстве по хранилища.