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

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

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

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

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

Ключевые ссылки

исходный код.
Пакет (npm)
Справочная документация по API
документации по продукту
Samples
REST API хранилища Azure

Начало работы

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

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

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

Prerequisites

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

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

npm install @azure/storage-blob

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

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

Azure Active Directory
Общий ключ
подписей общего доступа

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.

Веб-воркеры

Эта библиотека требует, чтобы некоторые объекты 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

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

CORS

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

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

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

Основные понятия

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

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

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

Учетная запись хранения, используемая черезBlobServiceClient
Контейнер в учетной записи хранения, используемый черезContainerClient
Большой двоичный объект в контейнере, используемый через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}`);
  }
}

Полный пример итерации контейнеров можно найти в 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}`);
}

Полный пример итерации BLOB-объектов см. в 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();
}

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

Пожалуйста, обратитесь к разделу JavaScript Bundle для получения дополнительной информации об использовании этой библиотеки в браузере.

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}`);
}

Полный пример простых сценариев находится по адресу samples/v12/typescript/src/sharedKeyAuth.ts.

Troubleshooting

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

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

setLogLevel("info");

Дальнейшие шаги

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

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

Contributing

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по созданию и тестированию кода.

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

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-10-17