Partilhar via

Biblioteca de cliente de Blob de Armazenamento do Azure para JavaScript - versão 12.24.0

  • Artigo

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

Primeiros passos

Ambientes atualmente suportados

Consulte o nosso de política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure
  • Uma conta de armazenamento

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, ContainerClientou BlobClient por exemplo. Consulte exemplos para criar o BlobServiceClient para saber mais sobre autenticação.

Azure Ative 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 README para @azure/identity para obter mais detalhes e exemplos para começar.

Compatibilidade

Esta biblioteca é compatível com Node.js e navegadores, e validada em relação às 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 de 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 "APENAS DISPONÍVEL EM TEMPO DE EXECUÇÃO NODE.JS" ou "DISPONÍVEL APENAS EM NAVEGADORES".

  • Se um blob contiver dados compactados em formato gzip ou deflate e sua codificação de conteúdo for definida de acordo, o comportamento de download será 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 de compartilhamento de recursos entre origens (Cross-Origin Resourcesharing) 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 usada via BlobServiceClient
  • Um contêiner na conta de armazenamento usada via ContainerClient
  • Um de blob em um recipiente usado via

Exemplos

Importar o pacote

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

const AzureStorageBlob = require("@azure/storage-blob");

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@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 parâmetro options.

com DefaultAzureCredential de @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 - /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) - /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 - /azure/storage/common/storage-auth-aad-rbac-portal.
    • No portal azure, vá para 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 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).
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@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 de exemplo Azure AD Auth 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 método estático fromConnectionString() 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]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

com StorageSharedKeyCredential

Como alternativa, você instancia um BlobServiceClient com um StorageSharedKeyCredential passando nome-conta e chave-conta 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]

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

// Enter your storage account name and shared key
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 SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS do Portal do Azure ou gerar um usando generateAccountSASQueryParameters().

const { BlobServiceClient } = require("@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.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  // 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);
}

main();

Listar os contêineres

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

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Alternativamente, sem usar for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Além disso, a paginação também é suportada para listagem através byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Para obter uma amostra completa sobre contêineres iterantes, consulte samples/v12/typescript/src/listContainers.ts.

Criar um blob carregando dados

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

Listar blobs dentro de um contêiner

Semelhante à listagem de contêineres.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

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)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  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();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [Node.js only] A helper method used to read 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);
    });
  }
}

main();

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.

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

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

async function main() {
  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 downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

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

Solução de problemas

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:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Próximos passos

Mais exemplos de código:

Contribuição

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 guia específico de armazenamento para obter informações adicionais sobre como configurar o ambiente de teste para bibliotecas de armazenamento.

Impressões