Biblioteca de clientes do Blob de Armazenamento do Azure para JavaScript – versão 12.29.1

O Blob de Armazenamento do Azure é a solução de armazenamento de objetos da Microsoft para a nuvem. O armazenamento de blobs é otimizado para armazenar grandes quantidades de dados não estruturados. Dados não estruturados são dados que não aderem a um modelo ou definição de dados específico, como texto ou dados binários.

Este projeto fornece uma biblioteca de clientes em JavaScript que facilita o consumo do serviço de Blob de Armazenamento do Microsoft Azure.

Use as bibliotecas de cliente neste pacote para:

Propriedades do serviço Get/Set Blob
Criar/listar/excluir contêineres
Criar/Ler/Listar/Atualizar/Excluir Blobs de Blocos
Criar/Ler/Listar/Atualizar/Excluir Blobs de Página
Criar/Ler/Listar/Atualizar/Excluir Blobs de Acréscimo

Links principais

código-fonte
Pacote (npm)
documentação de referência da API
Documentação do produto
Samples
APIs REST do Blob do Armazenamento do Azure

Como começar

Ambientes com suporte no momento

versões lts do Node.js
Versões mais recentes do Safari, Chrome, Edge e Firefox.

Consulte nossa política de suporte para obter mais detalhes.

Prerequisites

Uma assinatura do Azure
Uma conta de armazenamento

Instalar o pacote

A maneira preferida de instalar a biblioteca de clientes do Blob de Armazenamento do Azure para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela de terminal:

npm install @azure/storage-blob

Autenticar o cliente

O Armazenamento do Azure dá suporte a várias maneiras de autenticação. Para interagir com o serviço de Armazenamento de Blobs do Azure, você precisará criar uma instância de um cliente de Armazenamento – BlobServiceClient, ContainerClientou BlobClient, por exemplo. Consulte exemplos para criar o BlobServiceClient para saber mais sobre autenticação.

Azure Active Directory
Chave compartilhada
assinaturas de acesso compartilhado

Active Directory do Azure

O serviço de Armazenamento de Blobs do Azure dá suporte ao uso do Azure Active Directory para autenticar solicitações em suas APIs. O pacote @azure/identity fornece uma variedade de tipos de credencial que seu aplicativo pode usar para fazer isso. Consulte o README para @azure/identity para obter mais detalhes e exemplos para começar.

Compatibility

Essa biblioteca é compatível com Node.js e navegadores e validada em versões de Node.js LTS (>=8.16.0) e versões mais recentes do Chrome, Firefox e Edge.

Trabalhadores da Web

Essa biblioteca exige que determinados objetos DOM estejam disponíveis globalmente quando usados no navegador, que os trabalhos da Web não disponibilizam por padrão. Você precisará polifilá-los para fazer essa biblioteca funcionar em trabalhos web.

Para obter mais informações, consulte nossa documentação para usar o SDK do Azure para JS no Web Workers

Essa biblioteca depende das seguintes APIs do DOM que precisam de polyfills externos carregados quando usados em trabalhos Web:

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o runtime dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "SOMENTE DISPONÍVEL EM NODE.JS RUNTIME" ou "SOMENTE DISPONÍVEL EM NAVEGADORES".

Se um blob mantiver dados compactados no formato gzip ou deflate e sua codificação de conteúdo for definida adequadamente, o comportamento de download será diferente entre Node.js e navegadores. Em Node.js clientes de armazenamento baixarão o blob em seu formato compactado, enquanto nos navegadores os dados serão baixados em formato descompactado.

Recursos, interfaces, classes ou funções disponíveis apenas em Node.js

Autorização de chave compartilhada com base no nome da conta e na chave da conta
- StorageSharedKeyCredential
Geração de SAS (Assinatura de Acesso Compartilhado)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Carregamento e download paralelos. Observe que BlockBlobClient.uploadData() está disponível em Node.js e navegadores.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Recursos, interfaces, classes ou funções disponíveis somente em navegadores

Upload e download paralelos
- BlockBlobClient.uploadBrowserData()

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento.

CORS

Você precisa configurar regras de CORS (Compartilhamento de Recursos entre Origens) para sua conta de armazenamento se precisar desenvolver para navegadores. Acesse o portal do Azure e o Gerenciador de Armazenamento do Azure, localize sua conta de armazenamento, crie novas regras CORS para serviços de blob/fila/arquivo/tabela.

Por exemplo, você pode criar as seguintes configurações de CORS para depuração. Porém, personalize as configurações cuidadosamente de acordo com seus requisitos no ambiente de produção.

Origens permitidas: *
Verbos permitidos: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
Cabeçalhos permitidos: *
Cabeçalhos expostos: *
Idade máxima (segundos): 86400

Conceitos principais

O armazenamento de blobs foi projetado para:

Fornecendo imagens ou documentos diretamente para um navegador.
Armazenando arquivos para acesso distribuído.
Streaming de vídeo e áudio.
Gravando em arquivos de log.
Armazenando dados para backup e restauração, recuperação de desastre e arquivamento.
Armazenando dados para análise por um serviço local ou hospedado no Azure.

O Armazenamento de Blobs oferece três tipos de recursos:

A conta de armazenamento usada por meio de BlobServiceClient
Um contêiner na conta de armazenamento usado por meio de ContainerClient
Um blob em um contêiner usado por meio de BlobClient

Examples

Importar o pacote
Criar o cliente do serviço blob
Criar um novo contêiner
Listar os contêineres
Criar um blob carregando dados
Listar blobs dentro de um contêiner
Baixar um blob e convertê-lo em uma cadeia de caracteres (Node.js)
Baixar um blob e convertê-lo em uma cadeia de caracteres (Navegadores)

Importar o pacote

Para usar os clientes, importe o pacote para o arquivo:

import * as AzureStorageBlob from "@azure/storage-blob";

Como alternativa, importe seletivamente apenas os tipos necessários:

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

Criar o cliente de serviço de blob

O BlobServiceClient requer uma URL para o serviço de blob e uma credencial de acesso. Opcionalmente, ele também aceita algumas configurações no parâmetro options.

com `DefaultAzureCredential` de `@azure/identity` pacote

maneira recomendada de instanciar um BlobServiceClient

Instalação: Referência - Autorizar o acesso a blobs e filas com o Azure Active Directory de um aplicativo cliente - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

Registrar um novo aplicativo do AAD e conceder permissões para acessar o Armazenamento do Azure em nome do usuário conectado
- Registrar um novo aplicativo no Azure Active Directory (no portal do Azure) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- Na seção API permissions, selecione Add a permission e escolha Microsoft APIs.
- Escolha Azure Storage e marque a caixa de seleção ao lado de user_impersonation e clique em Add permissions. Isso permitiria que o aplicativo acessasse o Armazenamento do Azure em nome do usuário conectado.
Conceder acesso aos dados de Blob do Azure com RBAC no Portal do Azure
- Funções RBAC para blobs e filas - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- No portal do Azure, acesse sua conta de armazenamento e atribua função de Colaborador de Dados de Blob de Armazenamento ao aplicativo AAD registrado na guia Access control (IAM) (na barra de navegação do lado esquerdo da sua conta de armazenamento no portal do azure).
Configuração do ambiente para o exemplo
- Na página de visão geral do aplicativo AAD, anote o CLIENT ID e o TENANT ID. Na guia "Certificados & Segredos", crie um segredo e observe isso.
- Verifique se você tem AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET como variáveis de ambiente para executar com êxito o exemplo(Pode aproveitar process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

Consulte o exemplo de autenticação do Azure AD para obter um exemplo completo usando esse método.

[Observação - As etapas acima são apenas para Node.js]

usando a cadeia de conexão

Como alternativa, você pode criar uma instância de um BlobServiceClient usando o método estático fromConnectionString() com a cadeia de conexão completa como o argumento. (A cadeia de conexão pode ser obtida no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

com `StorageSharedKeyCredential`

Como alternativa, você cria uma instância de um BlobServiceClient com um StorageSharedKeyCredential passando o nome da conta e a chave da conta como argumentos. (O nome da conta e a chave de conta podem ser obtidos no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential,
);

com token SAS

Além disso, você pode criar uma instância de um BlobServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS no Portal do Azure ou gerar um usando generateAccountSASQueryParameters().

import { BlobServiceClient } from "@azure/storage-blob";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net?${sas}`);

Criar um novo contêiner

Use BlobServiceClient.getContainerClient() para obter uma instância de cliente de contêiner e, em seguida, criar um novo recurso de contêiner.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);

Listar os contêineres

Use BlobServiceClient.listContainers() função para iterar os contêineres, com a nova sintaxe for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

Como alternativa, sem usar for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

Além disso, há suporte para paginação para listagem também por meio de byPage():

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

Para obter um exemplo completo sobre contêineres de iteração, consulte samples/v12/typescript/src/listContainers.ts.

Criar um blob carregando dados

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

Listar blobs dentro de um contêiner

Semelhante à listagem de contêineres.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

Para obter um exemplo completo sobre blobs de iteração, consulte samples/v12/typescript/src/listBlobsFlat.ts.

Baixar um blob e convertê-lo em uma cadeia de caracteres (Node.js)

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

Baixe um blob e converta-o em uma cadeia de caracteres (Navegadores).

Consulte a seção JavaScript Bundle para obter mais informações sobre como usar essa biblioteca no navegador.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

Um exemplo completo de cenários simples está em samples/v12/typescript/src/sharedKeyAuth.ts.

Troubleshooting

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Próximas etapas

Mais exemplos de código:

de Exemplos de Armazenamento de Blobs (JavaScript)
exemplos de armazenamento de blobs (TypeScript)
casos de teste de armazenamento de blobs

Contributing

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Consulte também guia específico do Armazenamento para obter informações adicionais sobre como configurar o ambiente de teste para bibliotecas de armazenamento.

Comentários

Esta página foi útil?

Last updated on 2025-10-17