Carregar um blob com JavaScript ou TypeScript

• .NET
• Java
• JavaScript
• Python
• Ir

Este artigo mostra como carregar um blob usando a biblioteca de cliente do Armazenamento do Azure para JavaScript. Você pode carregar dados para um blob de bloco a partir de um caminho de arquivo, um fluxo, um buffer ou uma cadeia de caracteres de texto. Você também pode carregar 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 cliente do Armazenamento de Blobs do Azure para JavaScript. Para saber mais sobre como configurar seu projeto, incluindo instalação de pacotes, importação de módulos e criação de um objeto de cliente autorizado para trabalhar com recursos de dados, consulte Introdução ao Armazenamento de Blobs do Azure e JavaScript.
• O mecanismo de autorização deve ter permissões para executar uma operação de carregamento. Para saber mais, consulte as diretrizes de autorização para as seguintes operações de API REST:
  • Colocar Blob
  • Colocar Bloco

Carregar dados para um blob de bloco

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

• upload (método de carregamento não paralelo)
• carregarDados
• uploadFile (disponível apenas em tempo de execução Node.js)
• uploadStream (disponível apenas em tempo de execução Node.js)

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

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

O exemplo a seguir carrega um blob de bloco de um caminho de arquivo local:

JavaScript

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

TypeScript

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 bloco a partir de um fluxo

O exemplo a seguir carrega um blob de bloco criando um fluxo legível e carregando o fluxo:

JavaScript

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

TypeScript

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 bloco a partir de uma memória intermédia

O exemplo a seguir carrega um blob de bloco de um buffer de Node.js:

JavaScript

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

TypeScript

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 bloco a partir de uma cadeia de caracteres

O exemplo a seguir carrega um blob de bloco de uma cadeia de caracteres:

JavaScript

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

TypeScript

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 bloco com opções de configuração

Você pode definir opções de configuração da biblioteca do cliente ao carregar um blob. Essas opções podem ser ajustadas para melhorar o desempenho, aumentar 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 ao carregar

Você pode configurar 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:

Property	Description
blockSize	O tamanho máximo do bloco a ser transferido para cada solicitação como parte de uma operação de carregamento.
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 colocação, em vez de divididos em partes. Se os dados forem carregados em uma única captura, 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 nas amostras não pretendem ser uma recomendação. Para ajustar corretamente esses valores, você precisa considerar as necessidades específicas do seu aplicativo.

JavaScript

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

TypeScript

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.

Carregar um blob de bloco com tags de índice

As tags de índice de Blob categorizam os dados em sua conta de armazenamento usando atributos de tag chave-valor. Essas tags são automaticamente indexadas e expostas como um índice multidimensional pesquisável para encontrar dados facilmente.

O exemplo a seguir carrega um blob de bloco com tags de índice definidas usando BlockBlobParallelUploadOptions:

JavaScript

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

TypeScript

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 ao carregar

Você pode definir a camada de acesso de um blob no upload usando a interface BlockBlobParallelUploadOptions . O exemplo de código a seguir mostra como definir a camada de acesso ao carregar um blob:

JavaScript

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

TypeScript

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 definição da camada de acesso só é permitida para blobs de bloco. Você pode definir a camada de acesso para um blob de bloco como Hot, Cool, Coldou Archive. Para definir a camada de acesso como Cold, você deve usar uma versão mínima da biblioteca de cliente de 12.13.0.

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

Recursos

Para saber mais sobre como carregar blobs usando a biblioteca de cliente 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 que você interaja com operações da API REST por meio de paradigmas JavaScript familiares. Os métodos da biblioteca de cliente para carregar blobs usam as seguintes operações de API REST:

• Colocar Blob (API REST)
• Colocar bloco (API REST)

Amostras de código

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

• Carregar a partir do caminho do ficheiro local para JavaScript ou TypeScript
• Carregar a partir da memória intermédia para JavaScript ou TypeScript
• Upload do fluxo para JavaScript ou TypeScript
• Upload de string para JavaScript ou TypeScript
• Carregar com opções de transferência para JavaScript ou TypeScript
• Carregar com tags de índice para JavaScript ou TypeScript
• Carregar com camada de acesso para JavaScript ou TypeScript

Recursos da biblioteca do cliente

• Documentação de referência da biblioteca cliente
• Código fonte da biblioteca cliente
• Pacote (npm)

Consulte também

• Gerenciar e localizar dados de Blob do Azure com tags de índice de blob
• Usar marcas de índice de blob para gerenciar e localizar dados no Armazenamento de Blobs do Azure

Conteúdos relacionados

• Este artigo faz parte do guia do desenvolvedor do Armazenamento de Blobs para JavaScript/Typescript. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Crie seu aplicativo JavaScript/Typescript.