Carregar um blob com JavaScript ou TypeScript

  • Artigo

Este artigo mostra como carregar um blob usando a Biblioteca de clientes do Armazenamento do Microsoft Azure para Javascript. Você pode carregar dados em um blob de blocos de um caminho de arquivo, um fluxo, um buffer ou uma cadeia de caracteres de texto. Você também pode carregar blobs com marcas de índice.

Pré-requisitos

  • Os exemplos neste artigo pressupõem que você já tenha um projeto configurado para trabalhar com a biblioteca de clientes do Armazenamento de Blobs do Azure para JavaScript. Para saber mais sobre a configuração do seu projeto, incluindo a instalação de pacotes, a importação de módulos e a criação de um objeto cliente autorizado para trabalhar com recursos de dados, confira Introdução ao Armazenamento de Blobs do Azure e o JavaScript.
  • O mecanismo de autorização deve ter permissões para executar uma operação de upload. Para saber mais, confira as diretrizes de autorização para as seguintes operações de API REST:

Carregar dados em um blob de blocos

Você pode usar qualquer um dos seguintes métodos para carregar dados em um blob de blocos:

Cada um desses métodos pode ser chamado usando um objeto BlockBlobClient.

Carregar um blob de blocos a partir de um caminho de arquivo

O exemplo a seguir carrega um blob de blocos de um caminho de arquivo 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);
}

Carregar um blob de blocos de um fluxo

O exemplo a seguir faz o upload de um blob de blocos criando um fluxo legível e fazendo o upload do fluxo:

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

Carregar um blob de blocos a partir de um buffer

O seguinte exemplo faz o upload de um blob de blocos a partir de um 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);
}

Fazer upload um blob de blocos a partir de uma cadeia de caracteres

O seguinte exemplo carrega um blob de blocos de uma cadeia de caracteres:

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

Carregar um blob de blocos com opções de configuração

Você pode definir opções de configuração da biblioteca de clientes ao carregar um blob. Essas opções podem ser ajustadas para melhorar o desempenho, melhorar a confiabilidade e otimizar os custos. Os exemplos de código nesta seção mostram como definir opções de configuração usando a interface BlockBlobParallelUploadOptions e como passar essas opções como um parâmetro para uma chamada de método de upload.

Especificar opções de transferência de dados durante o upload

Você pode configurar as propriedades em BlockBlobParallelUploadOptions para melhorar o desempenho das operações de transferência de dados. A tabela a seguir lista as propriedades que você pode configurar, juntamente com uma descrição:

Propriedade Descrição
blockSize O tamanho máximo do bloco a ser transferido para cada solicitação como parte de uma operação de upload.
concurrency O número máximo de solicitações paralelas que são emitidas a qualquer momento como parte de uma única transferência paralela.
maxSingleShotSize Se o tamanho dos dados for menor ou igual a esse valor, eles serão carregados em uma única entrada, em vez de divididos em partes. Se os dados forem carregados de uma só vez, o tamanho do bloco será ignorado. O valor padrão é 256 MiB.

O exemplo de código a seguir mostra como definir valores para BlockBlobParallelUploadOptions e incluir as opções como parte de uma chamada de método de upload. Os valores fornecidos nestes exemplos têm a intenção de ser uma recomendação. Para ajustar adequadamente esses valores, você precisa considerar as necessidades específicas do seu aplicativo.

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

Para saber mais sobre como ajustar as opções de transferência de dados, consulte Ajuste de desempenho para uploads e downloads com JavaScript.

Carregar um blob de blocos com marcas de índice

As marcas de índice de blob categorizam os dados na sua conta de armazenamento usando atributos de marca de chave-valor. Essas marcas são indexadas automaticamente e expostas como um índice multidimensional pesquisável para localizar dados com facilidade.

O seguinte exemplo faz o upload de um blob de blocos com marcas de índice definidas 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': '2022-07-18',
    }
  }

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

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

Definir a camada de acesso de um blob durante o upload

Você pode definir a camada de acesso de um blob durante o upload usando a interface BlockBlobParallelUploadOptions. O exemplo de código a seguir mostra como definir a camada de acesso ao carregar um 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 = {
    // '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);
}

A configuração da camada de acesso somente é permitida para blobs de blocos. Você pode definir a camada de acesso para um blob de blocos como Hot, Cool, Cold ou Archive. Para definir a camada de acesso como Cold, você deve usar no mínimo a versão 12.13.0 da biblioteca de clientes.

Para saber mais sobre as camadas de acesso, confira Visão geral das camadas de acesso.

Recursos

Para saber mais sobre como carregar blobs usando a biblioteca de clientes do Armazenamento de Blobs do Azure para JavaScript, consulte os recursos a seguir.

Operações da API REST

O SDK do Azure para JavaScript contém bibliotecas que se baseiam na API REST do Azure, permitindo a interação com as operações de API REST por meio de paradigmas conhecidos do JavaScript. Os métodos da biblioteca de clientes para carregar blobs usam as seguintes operações da API REST:

Exemplos de código

Exibir exemplos de código deste artigo (GitHub):

Recursos da biblioteca de clientes

Confira também

Conteúdo relacionado

  • Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para JavaScript/TypeScript. Para saber mais, confira a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo JavaScript/TypeScript.