Carregar um blob com JavaScript ou TypeScript

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 fazer upload de blobs com tags 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:
- Colocar Blob
- Colocar Bloco

Fazer upload de dados para um blob de blocos

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

upload (método de carregamento não paralelo)
uploadData
uploadFile (disponível apenas no runtime do Node.js)
uploadStream (disponível apenas no runtime do Node.js)

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

Note

As bibliotecas de cliente do Armazenamento do Azure não dão suporte a gravações simultâneas no mesmo blob. Se seu aplicativo exigir vários processos gravando no mesmo blob, você deverá implementar uma estratégia de controle de simultaneidade para fornecer uma experiência previsível. Para saber mais sobre estratégias de simultaneidade, consulte Gerenciar simultaneidade no Armazenamentode Blobs.

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:

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

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:

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

Carregar um blob de blocos a partir de um buffer

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

Carregar um blob de blocos de uma cadeia de caracteres

O exemplo a seguir faz upload de um blob de blocos a partir de uma cadeia de caracteres:

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

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 nos exemplos não têm a intenção de servir como recomendação. Para ajustar adequadamente esses valores, você precisa considerar as necessidades específicas do seu aplicativo.

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

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

Especificar a validação de transferência de dados no upload

A validação de transferência com CRC64 fornece integridade de dados no nível do cliente para Armazenamento de Blobs do Azure, permitindo que você verifique se os dados enviados pelo aplicativo são os mesmos dados armazenados e lidos de Azure. Quando habilitado, o SDK de Blob calcula e valida somas de verificação CRC64 durante operações de upload e download, enquanto o serviço calcula e valida de forma independente as somas de verificação CRC64 para os dados recebidos e retornados. A validação é executada em cada solicitação e em todo o fluxo de dados completo, garantindo que todo o blob seja verificado mesmo quando os dados são transferidos em partições, como uploads de bloco ou leituras de intervalo. Consulte o Formato do Corpo Estruturado para obter mais detalhes.

As opções de validação de transferência podem ser definidas no nível do cliente usando BlobClientConfig, que aplica opções de validação a todos os métodos chamados de uma instância de BlobClient . Como alternativa, você pode substituir as opções de validação de transferência no nível da operação por meio de opções, como 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",
   },
);

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:

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

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:

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

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:

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

Exemplos de código

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

Fazer upload a partir de um caminho de arquivo local para JavaScript ou TypeScript
Carregar do buffer para JavaScript ou TypeScript
Fazer upload via stream para JavaScript ou TypeScript
Upload a partir de string para JavaScript ou TypeScript
Fazer upload com opções de transferência para JavaScript ou TypeScript
Carregar com marcas de índice para JavaScript ou TypeScript
Fazer upload com camada de acesso para JavaScript ou TypeScript

Recursos da biblioteca de clientes

Confira também

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.

Comentários

Esta página foi útil?

Last updated on 2026-06-19