Definir ou alterar o nível de acesso de um blob de bloco com JavaScript ou TypeScript

Artigo
11/02/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 clientes do Armazenamento de Blobs do Azure para JavaScript. Para saber como configurar seu projeto, incluindo a instalação do pacote, adicionando diretivas e criando um objeto cliente autorizado, veja 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 as seguintes operações de API REST:
- Definir camada do blob

Sobre as camadas de acesso de blob de blocos

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 blob

As camadas de acesso do Armazenamento do Azure incluem:

Camada quente – uma camada online otimizada para armazenar dados acessados ou modificados com frequência. A camada quente tem os custos de armazenamento mais altos, mas os custos de acesso mais baixos.
Camada fria – uma camada online otimizada para armazenar dados acessados ou modificados com pouca frequência. Os dados na camada fria devem ser armazenados por um mínimo de 30 dias. A camada fria tem custos de armazenamento mais baixos e custos de acesso mais altos em comparação com a camada quente.
Camada de acesso frio: uma camada online otimizada para armazenar dados acessados ou modificados com pouca frequência. Os dados na camada acesso frio devem ser armazenados por um mínimo de 90 dias. A camada de acesso frio tem custos de armazenamento mais baixos e custos de acesso mais altos em comparação com a camada de acesso esporádico.
Camada de arquivos: uma camada offline otimizada para armazenar dados acessados raramente e com requisitos de latência flexíveis, na ordem de horas. Os dados na camada de arquivos devem ser armazenados por um mínimo de 180 dias.

Para saber mais sobre as modalidades de acesso, confira Camadas de acesso de dados do blob.

Enquanto um blob estiver na camada de acesso aos arquivos, ele será considerado offline e não poderá ser lido nem alterado. Para ler ou modificar dados em um blob arquivado, primeiro você deve reidratar o blob para uma camada online. Para saber mais sobre como reidratar um blob da Camada de arquivos para uma camada online, confira Reidratação de blobs da Camada de arquivos.

Restrições

A configuração da camada de acesso somente é permitida em blobs de blocos. Para saber mais sobre restrições na configuração da camada de acesso de um blob de blocos, consulte Definir Camada de Blob (API REST).

Observação

Para configurar a camada de acesso como Cold usando o JavaScript, você deve usar no mínimo a versão 12.13.0 da biblioteca de clientes.

Definir a camada de acesso de um blob durante o upload

Para carregar um blob em uma camada de acesso específica, use BlockBlobUploadOptions. As opções da propriedade tier 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 upload

Para alterar a camada de acesso de um blob depois que ele for 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 blocos de um estado arquivado. Os possíveis valores 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

Para copiar um blob, use o método BlobClient.beginCopyFromURL. Para alterar a camada de acesso durante a operação de cópia, use a propriedade BlobBeginCopyFromURLOptionstier e especifique uma camada de acesso diferente daquela 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.

Criar um BlobBatchClient. Use o cliente para criar um lote com o método createBatch(). Quando o lote estiver pronto, envie o lote para processamento. Use a estrutura retornada para validar se 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}`
    );
  }
}

Exemplos de código

Definir nível de acesso de blob durante upload para JavaScript ou TypeScript
Alterar nível de acesso do blob após upload para JavaScript ou TypeScript
Copie o blob para uma camada de acesso diferente para JavaScript ou TypeScript
Use um lote para alterar o nível de acesso para muitos blobs para JavaScript ou TypeScript

Compartilhar via