Partilhar via

Azure Storage Blob client library for JavaScript - version 12.31.0

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

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

Use as bibliotecas de cliente neste pacote para:

  • Obter/Definir Propriedades do Serviço de Blob
  • Criar/Listar/Excluir Contêineres
  • Criar/Ler/Listar/Atualizar/Excluir Blobs de Bloco
  • Criar/Ler/Listar/Atualizar/Excluir Blobs de Página
  • Criar/Ler/Listar/Atualizar/Excluir Blobs de Acréscimo

Ligações principais

Como Começar

Ambientes atualmente suportados

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

Prerequisites

Instalar o pacote

A maneira preferida de instalar a biblioteca de cliente de Blob de Armazenamento do Azure para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela do 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, ContainerClient, ou BlobClient por exemplo. Consulte exemplos para criar o para saber mais sobre autenticação BlobServiceClient .

Azure Active Directory

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

Compatibility

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

Trabalhadores da Web

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

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

Essa biblioteca depende das seguintes APIs DOM que precisam de polipreenchimentos externos carregados quando usados em web workers:

Diferenças entre Node.js e navegadores

Há diferenças entre Node.js e o tempo de execução dos navegadores. Ao começar a usar essa biblioteca, preste atenção às APIs ou classes marcadas com "SOMENTE DISPONÍVEL EM NODE.JS TEMPO DE EXECUÇÃO" ou "SOMENTE DISPONÍVEL EM NAVEGADORES".

  • Se um blob contém dados compactados em gzip formato ou deflate e sua codificação de conteúdo é definida de acordo, o comportamento de download é diferente entre Node.js e navegadores. No Node.js os clientes de armazenamento baixarão o blob em seu formato compactado, enquanto nos navegadores os dados serão baixados em formato descompactado.
Funcionalidades, interfaces, classes ou funções disponíveis apenas no Node.js
  • Autorização de chave compartilhada com base no nome da conta e na chave da conta
    • StorageSharedKeyCredential
  • Geração de Assinatura de Acesso Compartilhado (SAS)
    • generateAccountSASQueryParameters()
    • generateBlobSASQueryParameters()
  • Upload e download paralelos. Observe que BlockBlobClient.uploadData() está disponível em Node.js e navegadores.
    • BlockBlobClient.uploadFile()
    • BlockBlobClient.uploadStream()
    • BlobClient.downloadToBuffer()
    • BlobClient.downloadToFile()
Funcionalidades, interfaces, classes ou funções disponíveis apenas em browsers
  • Upload e download paralelos
    • BlockBlobClient.uploadBrowserData()

Pacote JavaScript

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

CORS

Você precisa configurar regras de compartilhamento de recursos entre origens (CORS) para sua conta de armazenamento se precisar desenvolver para navegadores. Vá para o portal do Azure e o Gerenciador de Armazenamento do Azure, encontre 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. Mas por favor, personalize as configurações cuidadosamente de acordo com suas necessidades 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-chave

O armazenamento de Blob foi projetado para:

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

O armazenamento de Blob oferece três tipos de recursos:

  • A conta de armazenamento utilizada através de BlobServiceClient
  • Um recipiente na conta de armazenamento usado via ContainerClient
  • Um blob em um recipiente usado via BlobClient

Examples

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. Ele também aceita opcionalmente algumas configurações no options parâmetro.

com DefaultAzureCredential a partir do @azure/identity pacote

Maneira recomendada de instanciar um BlobServiceClient

Configuração : Referência - Autorizar o acesso a blobs e filas com o Azure Ative Directory a partir de um aplicativo cliente - https://dori-uw-1.kuma-moon.com/azure/storage/common/storage-auth-aad-app

  • Registrar um novo aplicativo AAD e conceder permissões para acessar o Armazenamento do Azure em nome do usuário conectado

    • Registrar um novo aplicativo no Azure Ative Directory(no azure-portal) - https://dori-uw-1.kuma-moon.com/azure/active-directory/develop/quickstart-register-app
    • API permissions Na seção, selecione Add a permission e escolha Microsoft APIs.
    • Marque 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

  • Configuração do ambiente para o exemplo

    • Na página de visão geral do seu aplicativo AAD, anote o CLIENT ID e TENANT ID. Na guia "Certificados & Segredos", crie um segredo e anote isso.
    • Certifique-se de ter AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET como variáveis de ambiente para executar com êxito a amostra(Pode alavancar 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.

[Nota - Os passos acima são apenas para Node.js]

Usando a cadeia de conexão

Como alternativa, você pode instanciar um BlobServiceClient usando o fromConnectionString() método estático com a cadeia de conexão completa como argumento. (A cadeia de conexão pode ser obtida no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO NODE.JS]

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Como alternativa, você instancia um BlobServiceClient com um StorageSharedKeyCredential passando account-name e account-key como argumentos. (O nome da conta e a chave da conta podem ser obtidos no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO NODE.JS]

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 instanciar um BlobServiceClient com uma assinatura de acesso compartilhado (SAS). Você pode obter o token SAS do Portal do Azure ou gerar um usando generateAccountSASQueryParameters()o .

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, crie 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() a função para iterar os contêineres, com a nova for-await-of sintaxe:

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

Em alternativa, sem utilizar 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, a paginação também é suportada para listagem através 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 uma amostra completa sobre contêineres iterantes, 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 a iteração de blobs , consulte samples/v12/typescript/src/listBlobsFlat.ts.

Baixe um blob e converta-o em uma string (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 string (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 tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Mais exemplos de código:

Contributing

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

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

  • Last updated on