Definir ou alterar a camada de acesso de um blob de bloco com JavaScript ou TypeScript

Artigo
10/31/2024

Este artigo mostra como definir ou alterar a camada de acesso de um blob para blobs de bloco com a biblioteca de cliente do Armazenamento do Azure para JavaScript.

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 definir a camada de acesso do blob. Para saber mais, consulte as diretrizes de autorização para a seguinte operação da API REST:
- Set Blob Tier (Definir Camada de Blob)

Sobre as camadas de acesso de blob de bloco

Para gerenciar os custos das necessidades de armazenamento, pode ser útil organizar seus dados com base na frequência com que são acessados e por quanto tempo precisam ser retidos. O armazenamento do Azure oferece diferentes camadas de acesso para que você possa armazenar seus dados de blob da maneira mais econômica com base em como eles estão sendo usados.

Camadas de acesso para dados de blobs

As camadas de acesso do Armazenamento do Azure incluem:

Hot tier - Uma camada online otimizada para armazenar dados que são acessados ou modificados com frequência. O nível quente tem os custos de armazenamento mais altos, mas os menores custos de acesso.
Camada legal - Uma camada online otimizada para armazenar dados que são acessados ou modificados com pouca frequência. Os dados na camada fria devem ser armazenados por um período mínimo de 30 dias. O nível frio tem custos de armazenamento mais baixos e custos de acesso mais altos em comparação com o nível quente.
Camada fria - Uma camada online otimizada para armazenar dados acessados ou modificados com pouca frequência. Os dados na camada de acesso infrequente devem ser armazenados durante um mínimo de 90 dias. A camada de acesso infrequente tem custos de armazenamento inferiores e custos de acesso superiores em comparação com a camada de acesso esporádico.
Camada de arquivamento - Uma camada offline otimizada para armazenar dados que raramente são acessados e que tem requisitos de latência flexíveis, na ordem das horas. Os dados na camada de arquivo devem ser armazenados por um período mínimo de 180 dias.

Para saber mais sobre camadas de acesso, consulte Camadas de acesso para dados de blob.

Embora um blob esteja na camada de acesso Arquivo, ele é considerado offline e não pode ser lido ou modificado. Para ler ou modificar dados em um blob arquivado, você deve primeiro reidratar o blob para uma camada online. Para saber mais sobre como reidratar um blob da camada Arquivo para uma camada online, consulte Reidratação de Blob da camada Arquivo.

Restrições

A definição da camada de acesso só é permitida em blobs de bloco. Para saber mais sobre as restrições na definição da camada de acesso de um blob de bloco, consulte Definir camada de blob (API REST).

Nota

Para definir a camada de acesso para Cold usar JavaScript, você deve usar uma versão mínima da biblioteca de cliente 12.13.0.

Definir a camada de acesso de um blob durante o carregamento

Para carregar um blob em uma camada de acesso específica, use BlockBlobUploadOptions . As tier opções de propriedade são: Hot, Cool, Cold, ou Archive.

JavaScript
TypeScript

async function uploadWithAccessTier(containerClient, blobName) {

  const fileContentsAsString = `Hello from a string`

  // upload blob to `Cool` access tier
  const uploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool',
  }

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

  // Upload string
  await blockBlobClient.upload(fileContentsAsString, fileContentsAsString.length, uploadOptions);

  // Return client to continue with other operations
  return blockBlobClient;
}

async function uploadWithAccessTier(
  containerClient: ContainerClient,
  blobName: string
): Promise<BlockBlobClient> {

  const fileContentsAsString = `Hello from a string`;

  // Upload blob to cool tier
  const uploadOptions: BlockBlobUploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool',
  };

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

  // Upload string
  const uploadResult = await blockBlobClient.upload(
    fileContentsAsString,
    fileContentsAsString.length,
    uploadOptions
  );

  if (uploadResult.errorCode) throw Error(uploadResult.errorCode);

  // Return client to continue with other operations
  return blockBlobClient;
}

Alterar a camada de acesso de um blob após o carregamento

Para alterar a camada de acesso de um blob depois que ele é carregado no armazenamento, use setAccessTier. Junto com a camada, você pode definir a prioridade de reidratação da propriedade BlobSetTierOptions para tirar o blob de bloco de um estado arquivado. Os valores possíveis são High ou Standard.

JavaScript
TypeScript

async function main(blockBlobClient) {

  // Get current access tier
  const { accessTier } = await blockBlobClient.getProperties();
  console.log(`Current access tier: ${accessTier}`);

  // 'Hot', 'Cool', or 'Archive'
  const newAccessTier = 'Cool';

  // Rehydrate priority: 'High' or 'Standard'
  const rehydratePriority = 'High';

  const result = await blockBlobClient.setAccessTier(
    newAccessTier,
    { rehydratePriority }
  );

  if (result?.errorCode == undefined) {
    console.log(`Change to access was successful`);
  } else {
    console.log(result);
  }
}

async function main(blockBlobClient: BlockBlobClient): Promise<void> {
  const options: BlobGetPropertiesOptions = {};

  // Get current access tier
  const { errorCode, accessTier } = await blockBlobClient.getProperties(
    options
  );
  if (!errorCode) {
    console.log(`Current access tier: ${accessTier}`);
  }

  // 'Hot', 'Cool', or 'Archive'
  const newAccessTier = 'Cool';

  // Rehydrate priority: 'High' or 'Standard'
  const tierOptions: BlobSetTierOptions = {
    rehydratePriority: 'High'
  };

  const result: BlobSetTierResponse = await blockBlobClient.setAccessTier(
    newAccessTier,
    tierOptions
  );

  if (!result?.errorCode) {
    console.log(`Change to access was successful`);
  } else {
    console.log(result);
  }
}

Copiar um blob para uma camada de acesso diferente

Use o BlobClient.método beginCopyFromURL para copiar um blob. Para alterar a camada de acesso durante a operação de cópia, use a propriedade BlobBeginCopyFromURLOptions tier e especifique uma camada de acesso diferente do blob de origem.

JavaScript
TypeScript

async function copyBlobWithDifferentAccessTier(containerClient) {

  // create blob clients
  const sourceBlobClient = containerClient.getBlobClient(originalBlob);
  const destinationBlobClient = containerClient.getBlobClient(copyBlob);

  // start copy, access tiers include `Hot`, `Cool`, `Cold`, `Archive`
  const copyPoller = await destinationBlobClient.beginCopyFromURL(sourceBlobClient.url, { tier: 'Hot' });
  console.log('start copy from original to copy');

  // wait until done
  await copyPoller.pollUntilDone();
  console.log('copy finished')
}

async function copyBlobWithDifferentAccessTier(
  containerClient: ContainerClient
): Promise<void> {

  // create blob clients
  const sourceBlobClient: BlobClient = containerClient.getBlobClient(
    originalBlob
  );
  const destinationBlobClient: BlobClient = containerClient.getBlobClient(
    copyBlob
  );

  const copyOptions: BlobBeginCopyFromURLOptions = { tier: 'Hot' };

  // start copy, access tiers include `Hot`, `Cool`, `Cold`, `Archive`
  const copyPoller = await destinationBlobClient.beginCopyFromURL(
    sourceBlobClient.url,
    copyOptions
  );
  console.log('start copy from original to copy');

  // wait until done
  await copyPoller.pollUntilDone();
  console.log('copy finished');
}

Usar um lote para alterar a camada de acesso para muitos blobs

O lote representa um conjunto agregado de operações em blobs, como excluir ou definir a camada de acesso. Você precisa passar a credencial correta para executar cada operação com êxito. Neste exemplo, a mesma credencial é usada para um conjunto de blobs no mesmo contêiner.

Crie um BlobBatchClient. Use o cliente para criar um lote com o método createBatch( ). Quando o lote estiver pronto, envie-o para processamento. Use a estrutura retornada para validar que a operação de cada blob foi bem-sucedida.

JavaScript
TypeScript

async function main(containerClient) {

  // Prep array
  const blockBlobCount = 3;
  const blockBlobClients = new Array(blockBlobCount);

  // Create container and blobs in `Hot` tier
  await prepContainer(containerClient, blockBlobCount, blockBlobClients);

  // Blob batch client and batch
  const containerScopedBatchClient = containerClient.getBlobBatchClient();
  const blobBatch = containerScopedBatchClient.createBatch();

  // Assemble batch to set tier to `Cool` tier
  for (let i = 0; i < blockBlobCount; i++) {
    await blobBatch.setBlobAccessTier(blockBlobClients[i].url, sharedKeyCredential, "Cool", {});
  }

  // Submit batch request and verify response
  const resp = await containerScopedBatchClient.submitBatch(blobBatch, {});
  console.log(`Requested ${blockBlobCount}, batched ${resp.subResponses.length}, success ${resp.subResponsesSucceededCount}, failure ${resp.subResponsesFailedCount}`);

  // Examine each batch item
  for (let i = 0; i < blockBlobCount; i++) {

    // Check blob tier set properly
    const resp2 = await blockBlobClients[i].getProperties();
    console.log(`[${i}] access tier ${resp2.accessTier}, status ${resp.subResponses[i].status}, message ${resp.subResponses[i].statusMessage}`)
  }
}

async function batchChangeAccessTier(
  containerClient: ContainerClient
): Promise<void> {
  // Prep array
  const blockBlobCount = 3;
  const blockBlobClients: BlockBlobClient[] = new Array(blockBlobCount);

  // Create container and blobs in `Hot` tier
  await prepContainer(containerClient, blockBlobCount, blockBlobClients);

  // Blob batch client and batch
  const containerScopedBatchClient: BlobBatchClient =
    containerClient.getBlobBatchClient();
  const blobBatch: BlobBatch = containerScopedBatchClient.createBatch();

  // Assemble batch to set tier to `Cool` tier
  for (let i = 0; i < blockBlobCount; i++) {
    await blobBatch.setBlobAccessTier(
      blockBlobClients[i].url,
      sharedKeyCredential,
      'Cool',
      {}
    );
  }

  // Submit batch request and verify response
  const resp = await containerScopedBatchClient.submitBatch(blobBatch, {});

  if (resp.errorCode) throw Error(resp.errorCode);

  console.log(
    `Requested ${blockBlobCount}, batched ${resp.subResponses.length}, success ${resp.subResponsesSucceededCount}, failure ${resp.subResponsesFailedCount}`
  );

  // Examine each batch item
  for (let i = 0; i < blockBlobCount; i++) {
    // Check blob tier set properly
    const resp2 = await blockBlobClients[i].getProperties();

    if (resp2.errorCode) throw Error(resp2.errorCode);

    console.log(
      `[${i}] access tier ${resp2.accessTier}, status ${resp.subResponses[i].status}, message ${resp.subResponses[i].statusMessage}`
    );
  }
}

Amostras de código

Definir a camada de acesso de blob durante o upload para JavaScript ou TypeScript
Alterar a camada de acesso de blob após o upload para JavaScript ou TypeScript
Copiar blob em camada de acesso diferente para JavaScript ou TypeScript
Usar um lote para alterar a camada de acesso para muitos blobs para JavaScript ou TypeScript

Partilhar via