Cargar un blob con JavaScript

  • Artículo

En este artículo se muestra cómo cargar un blob con la biblioteca cliente de Azure Storage para JavaScript. Puede cargar datos en un blob en bloques desde una ruta de acceso de archivo, una secuencia, un búfer o una cadena de texto. También puede cargar blobs con etiquetas de índice.

Requisitos previos

  • Los ejemplos de este artículo asumen que ya tiene un proyecto configurado para trabajar con la librería cliente Azure Blob Storage para JavaScript. Para obtener más información sobre la configuración del proyecto, incluida la instalación de paquetes, la importación de módulos y la creación de un objeto cliente autorizado para trabajar con recursos de datos, consulte Introducción a Azure Blob Storage y JavaScript.
  • El mecanismo de autorización debe tener permisos para realizar una operación de carga. Para más información, consulte la guía de autorización para las siguientes operaciones de la API de REST:

Carga de datos en un blob en bloques

Puede usar cualquiera de los métodos siguientes para cargar datos en un blob en bloques:

Se puede llamar a cada uno de estos métodos mediante un objeto BlockBlobClient.

Carga de un blob en bloques desde una ruta de acceso de archivo

El siguiente ejemplo carga un blob de bloque desde una ruta de archivo local:

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

Carga de un blob en bloques desde una secuencia

En el siguiente ejemplo se carga un blob en bloques al crear y cargar un flujo legible:

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

Carga de un blob en bloques desde un búfer

El siguiente ejemplo carga un blob de bloques desde un buffer Node.js:

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

Carga de un blob en bloques desde una cadena

El siguiente ejemplo carga un blob de bloque desde una cadena:

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

Carga de un blob en bloques con opciones de configuración

Puede definir las opciones de configuración de la biblioteca cliente al cargar un blob. Estas opciones se pueden ajustar para mejorar el rendimiento, mejorar la confiabilidad y optimizar los costes. Los ejemplos de código de esta sección muestran cómo establecer las opciones de configuración usando la interfaz BlockBlobParallelUploadOptions y cómo pasar esas opciones como parámetro a una llamada al método de carga.

Especificación de opciones de transferencia de datos al cargar

Puede configurar las propiedades en BlockBlobParallelUploadOptions para mejorar el rendimiento de las operaciones de transferencia de datos. En la tabla siguiente se enumeran las propiedades que puede configurar, junto con una descripción:

Propiedad Descripción
blockSize Tamaño máximo de bloque que se va a transferir para cada solicitud como parte de una operación de carga.
concurrency El número máximo de solicitudes paralelas que se emiten en cualquier momento dado como parte de una única transferencia paralela.
maxSingleShotSize Si el tamaño de los datos fuera menor o igual que este valor, se cargará en una sola colocación en lugar de dividirse en fragmentos. Si los datos se cargasen en una sola captura, se omitirá el tamaño del bloque. El valor predeterminado es 256 MiB.

El siguiente ejemplo de código muestra cómo establecer valores para BlockBlobParallelUploadOptions e incluir las opciones como parte de una llamada al método de carga. Los valores proporcionados en las muestras no pretenden ser una recomendación. Para ajustar correctamente estos valores, debe tener en cuenta las necesidades específicas de la aplicación.

// 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 index tags
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Carga de un blob en bloques con etiquetas de índice

Las etiquetas de índice de blobs clasifican los datos de la cuenta de almacenamiento mediante atributos de etiqueta clave-valor. Estas etiquetas se indexan y se exponen automáticamente como un índice multidimensional que se puede buscar para encontrar fácilmente los datos.

El siguiente ejemplo carga un blob de bloque con etiquetas de índice establecidas usando BlockBlobParallelUploadOptions:

// 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': '2023-06-01',
    }
  }

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

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

Establecimiento del nivel de acceso de un blob durante la carga

El uso de la interfaz BlockBlobParallelUploadOptions permite establecer el nivel de acceso de un blob al cargarlo. En el ejemplo de código siguiente se muestra cómo establecer el nivel de acceso al cargar un blob:

// 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 = {
    tier: 'Cool',
  }

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

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

Solo se permite establecer el nivel de acceso en los blobs en bloques. Puede establecer el nivel de acceso de un blob en bloques en Hot, Cool, Cold o Archive. Para establecer el nivel de acceso en Cold, debe usar la versión mínima de la biblioteca cliente 12.13.0.

Si desea obtener más información sobre los niveles de acceso, consulte Información general sobre los niveles de acceso.

Recursos

Para más información sobre cómo cargar listas de blobs con la biblioteca cliente de Azure Blob Storage para JavaScript, consulte los recursos siguientes.

Operaciones de API REST

El SDK de Azure para JavaScript contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST a través de paradigmas conocidos de JavaScript. Los métodos de la biblioteca cliente para cargar blobs usan las siguientes operaciones de API REST:

Ejemplos de código

Visualización de ejemplos de código de este artículo (GitHub):

Recursos de la biblioteca cliente

Consulte también