Introdução ao Armazenamento de Blobs do Azure e ao JavaScript

• .NET
• Java
• JavaScript
• TypeScript
• Python

Este artigo mostra como se conectar ao Armazenamento de Blobs do Azure usando a biblioteca de clientes v12 do Armazenamento de Blobs do Azure para JavaScript. Após se conectar, seu código pode operar em contêineres, blobs e recursos do serviço de Armazenamento de Blobs.

Os snippets de código de exemplo estão disponíveis no GitHub como arquivos Node.js executáveis.

Referência de API | Pacote (npm) | Código-fonte da biblioteca | Amostras | Enviar comentários

Pré-requisitos

• Assinatura do Azure - criar uma gratuitamente
• Conta de armazenamento do Azure – criar uma conta de armazenamento
• Node.js LTS
• Para aplicativos cliente (navegador), você precisa de ferramentas de agrupamento.

Configurar o seu projeto

1. Abra um prompt de comando e mude para a pasta do projeto. Altere YOUR-DIRECTORY para o nome da pasta:

   cd YOUR-DIRECTORY
   

2. Se você ainda não tiver um arquivo package.json no diretório, inicialize o projeto para criar o arquivo:

   npm init -y
   

3. Instale a biblioteca de clientes do Armazenamento de Blobs do Azure para JavaScript:

   npm install @azure/storage-blob
   

4. Se você quiser usar conexões sem senha usando o Microsoft Entra ID, instale a biblioteca de clientes da Identidade do Azure para JavaScript:

   npm install @azure/identity
   

Autorizar o acesso e se conectar ao Armazenamento de Blobs

O Microsoft Entra ID fornece a conexão mais segura gerenciando a identidade de conexão (identidade gerenciada). Essa funcionalidade sem senha permite que você desenvolva um aplicativo que não requer nenhum segredo (chaves ou cadeias de conexão) armazenado no código.

Configurar o acesso de identidade à nuvem do Azure

Para se conectar ao Azure sem senhas, você precisa configurar uma identidade do Azure ou usar uma identidade existente. Depois que a identidade for configurada, atribua as funções apropriadas à identidade.

Para autorizar o acesso sem senha com o Microsoft Entra ID, você precisará usar uma credencial do Azure. O tipo de credencial necessário depende do local em que o aplicativo é executado. Use essa tabela como um guia.

Ambiente	Método
Ambiente do Desenvolvedor	Visual Studio Code
Ambiente do Desenvolvedor	Entidade de serviço
Aplicativos hospedados no Azure	Configurar aplicativos hospedados
Local	Configuração do aplicativo local

Funções da conta de armazenamento

Seu recurso de armazenamento precisa ter uma ou mais das funções do Azure RBAC atribuídas ao recurso de identidade com o qual você planeja se conectar. Configure as funções do Armazenamento do Microsoft Azure para cada identidade criada na etapa anterior: nuvem do Azure, desenvolvimento local, local.

Depois de concluir a configuração, cada identidade precisa de pelo menos uma das funções apropriadas:

• Uma função de acesso a dados, como:

  • Leitor de Dados do Blob de Armazenamento
  • Colaborador de dados de blob de armazenamento

• Uma função de recurso, como:

  • Leitor
  • Colaborador

Crie seu aplicativo

Conforme você compila seu aplicativo, seu código interagirá principalmente com três tipos de recursos:

• A conta de armazenamento, que é o namespace exclusivo de nível superior para os dados de Armazenamento do Microsoft Azure.
• Contêineres, que organizam os dados de blob em sua conta de armazenamento.
• Blobs, que armazenam dados não estruturados, como texto e dados binários.

O diagrama a seguir mostra a relação entre esses recursos.

Cada tipo de recurso é representado por um ou mais clientes JavaScript associados:

Classe	Descrição
BlobServiceClient	Representa o ponto de extremidade do Armazenamento de Blob para sua conta de armazenamento.
ContainerClient	Permite manipular os contêineres do Armazenamento do Microsoft Azure e seus blobs.
BlobClient	Permite manipular os blobs do Armazenamento do Microsoft Azure.

Criar um objeto BlobServiceClient

O objeto BlobServiceClient é o principal objeto no SDK. Esse cliente permite que você manipule os serviços, contêineres e blobs.

Sem senha

Depois que as funções de identidade da conta de armazenamento do Azure e seu ambiente local forem configuradas, crie um arquivo JavaScript que inclua o pacote @azure/identity. Crie uma credencial, como DefaultAzureCredential, para implementar conexões sem senha com o Armazenamento de Blobs. Use essa credencial para autenticar com um objeto BlobServiceClient.

// connect-with-default-azure-credential.js
const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error('Azure Storage accountName not found');

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

O pacote dotenv é usado para ler o nome da conta de armazenamento de um arquivo .env. Esse arquivo não deve ser verificado no controle do código-fonte. Se você usar uma entidade de serviço local como parte da configuração DefaultAzureCredential, qualquer informação de segurança dessa credencial também entrará no arquivo .env.

Se você planeja implantar o aplicativo em servidores e clientes que são executados fora do Azure, crie uma das credenciais que atenda às suas necessidades.

Chave de conta

Crie um StorageSharedKeyCredential do nome da conta de armazenamento e da chave de conta. Em seguida, passe o StorageSharedKeyCredential para o construtor da classe BlobServiceClient para criar um cliente.

// connect-with-account-name-and-key.js
const { BlobServiceClient, StorageSharedKeyCredential } = require('@azure/storage-blob');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountName) throw Error('Azure Storage accountName not found');
if (!accountKey) throw Error('Azure Storage accountKey not found');

const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  sharedKeyCredential
);

async function main() {

  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);

}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

O pacote dotenv é usado para ler o nome da conta de armazenamento e chave de um arquivo .env. Esse arquivo não deve ser verificado no controle do código-fonte.

Para obter informações sobre como obter chaves de conta e diretrizes de melhores práticas para gerenciar e proteger corretamente suas chaves, consulte Gerenciar chaves de acesso da conta de armazenamento.

Token SAS

Crie um URI para o recurso usando o ponto de extremidade de serviço de blob e o token SAS. Em seguida, crie um BlobServiceClient com o URI. O token SAS é uma série de pares nome/valor na querystring no formato como:

https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN

Dependendo de qual ferramenta você usa para gerar seu token SAS, a querystring ? já pode ser adicionada ao token SAS.

// connect-with-sas-token.js
const { BlobServiceClient } = require('@azure/storage-blob');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
if (!accountName) throw Error('Azure Storage accountName not found');
if (!sasToken) throw Error('Azure Storage accountKey not found');

const blobServiceUri = `https://${accountName}.blob.core.windows.net`;

// https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN
const blobServiceClient = new BlobServiceClient(
  `${blobServiceUri}?${sasToken}`,
  null
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

O pacote dotenv é usado para ler o nome da conta de armazenamento e o token SAS de um arquivo .env. Esse arquivo não deve ser verificado no controle do código-fonte.

Para gerar e gerenciar tokens SAS, consulte qualquer um destes artigos:

• Conceder acesso limitado aos recursos de Armazenamento do Azure usando as SAS (assinaturas de acesso compartilhado)

• Criar uma SAS de serviço para um contêiner ou blob

Criar um objeto ContainerClient

Você pode criar o objeto ContainerClient do BlobServiceClient ou diretamente.

Criar objeto ContainerClient do BlobServiceClient

Criar objeto ContainerClient do BlobServiceClient.

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlobServiceClient,
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
  `${baseUrl}`,
  sharedKeyCredential
);

async function main() {
  try {
    // Create container client
    const containerClient = await blobServiceClient.getContainerClient(
      containerName
    );

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Criar ContainerClient diretamente

Sem senha

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Unique container name
const timeStamp = Date.now();
const containerName = `test`;

async function main() {
  try {
    
    // create container client from DefaultAzureCredential
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      new DefaultAzureCredential()
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }


  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Chave de conta

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

async function main() {
  try {
    // create container from ContainerClient
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      sharedKeyCredential
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }
    

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Token SAS

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Container must exist prior to running this script
const containerName = `test`;

// SAS token must have LIST permissions on container that haven't expired
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;

// Create SAS URL
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}?${sasToken}`;

async function main() {
  try {
    // create container client from SAS token
    const containerClient = new ContainerClient(sasUrl);

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }   
    
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

O pacote dotenv é usado para ler o nome da conta de armazenamento de um arquivo .env. Esse arquivo não deve ser verificado no controle do código-fonte.

Criar um objeto BlobClient

Você pode criar qualquer um dos objetos BlobClient, listados abaixo, de um ContainerClient ou diretamente.

Lista de clientes blob:

• BlobClient
• BlockBlobClient
• AppendBlobClient
• BlobLeaseClient
• PageBlobClient

Criar objeto BlobClient do ContainerClient

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

// Create ContainerClient
const containerClient = new ContainerClient(
  `${baseUrl}/${containerName}`,
  sharedKeyCredential
);  

async function main() {
  try {
  
    // Create BlobClient object
    const blobClient = containerClient.getBlobClient(blobName);

    // do something with blobClient...
    const properties = await blobClient.getProperties();
    console.log(`Blob ${blobName} properties:`);

    // get BlockBlobClient from blobClient
    const blockBlobClient = blobClient.getBlockBlobClient();

    // do something with blockBlobClient...
    const downloadResponse = await blockBlobClient.download(0);

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Criar BlobClient diretamente

Sem senha

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Container must exist prior to running this script
const containerName = `test`;

// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = "Hello there.";

async function main(){

  // Create a client that can authenticate with Azure Active Directory
  const client = new BlockBlobClient(
    `${baseUrl}/${containerName}/${blobName}`,
    new DefaultAzureCredential()
  );

  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${client.url}`);

  // Upload file contents
  const result = await client.upload(fileContentsAsString, fileContentsAsString.length);

  // Get results
  return result;
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

/*

Response looks like this:

{
  etag: '"0x8DAD247F1F4896E"',
  lastModified: 2022-11-29T20:26:07.000Z,
  contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
  clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
  requestId: '3580e726-201e-0045-1a30-0474f6000000',
  version: '2021-04-10',
  date: 2022-11-29T20:26:06.000Z,
  isServerEncrypted: true,
  'content-length': '0',
  server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
  'x-ms-content-crc64': 'BLv7vb1ONT8=',
  body: undefined
}
*/

Chave de conta

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlockBlobClient,
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

const fileContentsAsString = "Hello there.";

async function main() {
  try {

    // create blob from BlockBlobClient
    const blockBlobClient = new BlockBlobClient(
      `${baseUrl}/${containerName}/${blobName}`,
      sharedKeyCredential
    );

    // Upload data to the blob  
    await blockBlobClient.upload(
      fileContentsAsString,
      fileContentsAsString.length
    );
    console.log(`blob ${blockBlobClient.url} created`);
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Token SAS

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Container and blob must exist prior to running this script
// SAS token must have READ permissions on blob that haven't expired
const containerName = `test`;
const blobName = `my-text-file.txt`;

// Create SAS URL
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}?${sasToken}`;

// Utility function to convert a Node.js Readable stream into a Buffer
async function streamToBuffer(readableStream) {
  return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on('data', (data) => {
          chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on('end', () => {
          resolve(Buffer.concat(chunks));
      });
      readableStream.on('error', reject);
  });
}

async function main(){

  // Create a blob client from SAS token
  const client = new BlockBlobClient(sasUrl);

  // Get blob url
  console.log(`blob.url: ${client.url}`);

  // Download file contents
  const result = await client.download();
  const content = await streamToBuffer(result.readableStreamBody);

  // Get results
  return content.toString();
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

O pacote dotenv é usado para ler o nome da conta de armazenamento de um arquivo .env. Esse arquivo não deve ser verificado no controle do código-fonte.

Confira também

• Pacote (npm)
• Amostras
• Referência de API
• Código-fonte da biblioteca
• Enviar comentários