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

В этой статье показано, как загрузить объект BLOB с помощью клиентской библиотеки служба хранилища Azure для 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.

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

Проверка передачи с помощью CRC64-NVME обеспечивает целостность данных на уровне клиента для Хранилище BLOB-объектов Azure, что позволяет убедиться, что данные, отправленные приложением, совпадают с данными, хранящимися и считываемыми из Azure. Если этот параметр включен, Blob SDK вычисляет и проверяет контрольные суммы CRC64-NVME при операциях отправки и скачивания, а служба независимо вычисляет и проверяет контрольные суммы CRC64-NVME для данных, которые она получает и возвращает. Проверка выполняется для каждого запроса и по всему потоку данных, что гарантирует проверку всего BLOB-объекта, даже если данные передаются по частям, например при загрузке блоков или диапазонном чтении. Дополнительные сведения см. в формате структурированного текста .

Параметры проверки передачи можно определить на уровне клиента с помощью BlobClientConfig, который применяет параметры проверки ко всем методам, вызываемым из экземпляра BLOBClient . Кроме того, можно переопределить параметры проверки передачи на уровне операции с помощью параметров, таких как BlobUploadOptions.

JavaScript
TypeScript

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

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

Загрузить блочный 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-объектов с помощью клиентской библиотеки Хранилище BLOB-объектов Azure для JavaScript, см. следующие ресурсы.

Операции REST API

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

Размещение Blob (REST API)
Put Block (интерфейс REST API)

Примеры кода

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

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

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

См. также

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

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

Были ли сведения на этой странице полезными?

Last updated on 2026-06-16