Загрузка объекта типа Blob с помощью JavaScript или TypeScript

Статья
2025-04-01

В этой статье показано, как загрузить объект BLOB с помощью клиентской библиотеки Azure Storage для JavaScript. Данные можно загрузить в блочный blob из пути к файлу, потока, буфера или текстовой строки. Вы также можете загружать данные с индексными тегами.

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

В примерах этой статьи предполагается, что у вас уже есть проект, настроенный для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для JavaScript. Сведения о настройке проекта, включая установку пакетов, импорт модулей и создание авторизованного клиентского объекта для работы с ресурсами данных, см. в статье "Начало работы с Хранилище BLOB-объектов Azure и JavaScript".
Механизм авторизации должен иметь разрешения для выполнения операции отправки. Дополнительные сведения см. в руководстве по авторизации для следующих операций REST API:
- Добавить Blob
- Установить блок

Отправка данных в блочный BLOB-объект

Можно использовать любой из следующих методов для передачи данных в блочный блоб:

загрузка (метод непараллельной загрузки)
uploadData
uploadFile (доступно только в среде выполнения Node.js)
uploadStream (доступно только в среде выполнения Node.js)

Каждый из этих методов можно вызывать с помощью объекта BlockBlobClient .

Примечание.

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

Загрузка блочного BLOB-объекта из пути к файлу

В следующем примере загружается блочный blob из локального файла:

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadBlobFromLocalPath(containerClient, blobName, localFilePath){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

async function uploadBlobFromLocalPath(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

Загрузка блоб-блока из потока

В следующем примере загружается блоб-блок, создав поток для чтения и загрузив поток.

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// readableStream: Readable stream, for example, a stream returned from fs.createReadStream()
async function uploadBlobFromReadStream(containerClient, blobName, readableStream) {
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload data to block blob using a readable stream
  await blockBlobClient.uploadStream(readableStream);
}

async function uploadBlobFromReadStream(
  containerClient: ContainerClient,
  blobName: string,
  readStream: fs.ReadStream
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadStream(readStream);
}

Загрузка BLOB-объекта из буфера

В следующем примере загружается блоб-блок из буфера Node.js:

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// buffer: blob contents as a buffer, for example, from fs.readFile()
async function uploadBlobFromBuffer(containerClient, blobName, buffer) {

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

async function uploadBlobFromBuffer(
  containerClient: ContainerClient, blobName: string, buffer: Buffer
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

Отправка блочного BLOB-объекта из строки

В следующем примере загружается блочный Blob из строки:

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// fileContentsAsString: blob content
async function uploadBlobFromString(containerClient, blobName, fileContentsAsString){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContentsAsString, fileContentsAsString.length);
}

async function uploadBlobFromString(
  containerClient: ContainerClient,
  blobName: string,
  fileContents: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContents, fileContents.length);
}

Загрузка BLOB-объекта с параметрами конфигурации

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

Указание параметров передачи данных при отправке

Свойства можно настроить в BlockBlobParallelUploadOptions , чтобы повысить производительность операций передачи данных. В следующей таблице перечислены свойства, которые можно настроить, а также описание:

Свойство	Описание
`blockSize`	Максимальный размер блока для передачи для каждого запроса в рамках операции загрузки.
`concurrency`	Максимальное количество параллельных запросов, выдаваемых в любое время в рамках одной параллельной передачи.
`maxSingleShotSize`	Если размер данных меньше или равен этому значению, он передается в один раз, а не разбивается на блоки. Если данные загружаются разом, размер блока игнорируется. Значение по умолчанию — 256 МиБ.

В следующем примере кода показано, как задать значения для BlockBlobParallelUploadOptions и включить параметры в рамках вызова метода отправки. Значения, указанные в примерах, не предназначены для рекомендации. Чтобы правильно настроить эти значения, необходимо учитывать конкретные потребности приложения.

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithTransferOptions(containerClient, blobName, localFilePath) {
  
  // Specify data transfer options
  const uploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  } 

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with transfer options
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

async function uploadWithTransferOptions(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify data transfer options
  const uploadOptions: BlockBlobParallelUploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Дополнительные сведения о настройке параметров передачи данных см. в статье "Настройка производительности" для отправки и скачивания с помощью JavaScript.

Загрузить блочный BLOB-объект с тегами индекса

Теги индекса BLOB классифицируют данные в учетной записи хранения с помощью атрибутов тегов ключ-значение. Эти теги автоматически индексируются и представляются в виде многомерного индекса с поддержкой поиска для упрощения нахождения данных.

В следующем примере загружается блочный блоб с тегами индекса, заданными с помощью BlockBlobParallelUploadOptions:

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithIndexTags(containerClient, blobName, localFilePath) {
  
  // Specify index tags for blob
  const uploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with index tags
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

async function uploadBlobWithIndexTags(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify index tags for blob
  const uploadOptions: BlockBlobParallelUploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Установить уровень доступа объекта blob при загрузке

Уровень доступа большого двоичного объекта можно задать при загрузке с помощью интерфейса BlockBlobParallelUploadOptions. В следующем примере кода показано, как задать уровень доступа при загрузке большого двоичного объекта.

JavaScript
TypeScript

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithAccessTier(containerClient, blobName, localFilePath) {
  
  // Specify access tier
  const uploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool',
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob to cool tier
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

async function uploadBlobWithAccessTier(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {

  // Upload blob to 'Cool' access tier
  const uploadOptions: BlockBlobParallelUploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool'
  };

  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Установка уровня доступа разрешена только для блочных blob-объектов. Вы можете задать уровень доступа для блочного BLOB как Hot, Cool, Cold или Archive. Чтобы задать уровень Coldдоступа, необходимо использовать минимальную версию клиентской библиотеки 12.13.0.

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

Ресурсы

Чтобы узнать больше о загрузке BLOB-объектов с помощью клиентской библиотеки Azure Blob Storage для JavaScript, см. следующие ресурсы.

Операции REST API

Пакет SDK Azure для JavaScript содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API через знакомые парадигмы JavaScript. Методы клиентской библиотеки для отправки больших двоичных объектов используют следующие операции REST API:

Put Blob (REST API)
Put Block (REST API)

Примеры кода

Просмотрите примеры кода из этой статьи (GitHub):

Загрузка с локального пути к файлу для JavaScript или TypeScript
Отправка из буфера для JavaScript или TypeScript
Отправка из потока для JavaScript или TypeScript
Загрузка из строки для JavaScript или TypeScript
Отправка с параметрами передачи для JavaScript или TypeScript
Отправка с тегами индекса для JavaScript или TypeScript
Отправка с уровнем доступа для JavaScript или TypeScript

Ресурсы клиентской библиотеки

См. также

Эта статья является частью руководства разработчика по Blob Storage для JavaScript/TypeScript. Дополнительные сведения см. в полном списке статей руководства разработчика по созданию приложения JavaScript и TypeScript.