Biblioteca de cliente de Blobs de Armazenamento do Azure para JavaScript – versão 12.17.0

Artigo
11/15/2023

O Blob de Armazenamento do Azure é a solução de armazenamento de objetos da Microsoft para a cloud. O armazenamento de blobs está otimizado para armazenar quantidades em grande escala de dados não estruturados. Os dados não estruturados são dados que não seguem uma definição ou um modelo de dados em particular, como por exemplo, texto ou dados binários.

Este projeto fornece uma biblioteca de cliente no JavaScript que facilita a utilização Armazenamento do Microsoft Azure serviço Blob.

Utilize as bibliotecas de cliente neste pacote para:

Obter/Definir Propriedades do Serviço blob
Criar/Listar/Eliminar Contentores
Criar/Ler/Lista/Atualizar/Eliminar Blobs de Blocos
Criar/Ler/Lista/Atualizar/Eliminar Blobs de Página
Criar/Ler/Lista/Atualizar/Eliminar Blobs de Acréscimo

Ligações principais

Introdução

Ambientes atualmente suportados

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

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

Pré-requisitos

Uma subscrição do Azure
Uma Conta de Armazenamento

Instalar o pacote

A forma preferencial de instalar a biblioteca de cliente do Blob de Armazenamento do Azure para JavaScript é utilizar o gestor de pacotes npm. Escreva o seguinte numa janela de terminal:

npm install @azure/storage-blob

Autenticar o cliente

O Armazenamento do Azure suporta várias formas de autenticação. Para interagir com o serviço Armazenamento de Blobs do Azure, terá de criar uma instância de um cliente de Armazenamento – BlobServiceClient, ContainerClientouBlobClient, por exemplo. Veja exemplos para criar o BlobServiceClient para saber mais sobre a autenticação.

Azure Active Directory
Chave Partilhada
Assinaturas de acesso partilhado

Azure Active Directory

O serviço Armazenamento de Blobs do Azure suporta a utilização do Azure Active Directory para autenticar pedidos para as respetivas APIs. O @azure/identity pacote fornece uma variedade de tipos de credenciais que a sua aplicação pode utilizar para o fazer. Consulte o README para @azure/identity obter mais detalhes e exemplos para começar.

Compatibilidade

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

Web Workers

Esta biblioteca requer que determinados objetos DOM estejam disponíveis globalmente quando utilizados no browser, que os web workers não disponibilizam por predefinição. Terá de efetuar o polyfill para que esta biblioteca funcione em web workers.

Para obter mais informações, veja a nossa documentação para utilizar o SDK do Azure para JS em Web Workers

Esta biblioteca depende das seguintes APIs DOM que precisam de polifills externos carregados quando utilizados em trabalhos Web:

Diferenças entre Node.js e browsers

Existem diferenças entre Node.js e o runtime dos browsers. Ao começar a utilizar esta biblioteca, preste atenção às APIs ou às classes marcadas com "APENAS DISPONÍVEL NO NODE.JS RUNTIME" ou "APENAS DISPONÍVEL NOS BROWSERS".

Se um blob tiver dados comprimidos no formato ou deflate no formato e a respetiva codificação de conteúdos estiver definida em gzip conformidade, o comportamento de transferência é diferente entre Node.js e browsers. No Node.js os clientes de armazenamento transferirão o blob no seu formato comprimido, enquanto nos browsers os dados serão transferidos em formato descomprimido.

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

Autorização de Chave Partilhada com base no nome da conta e na chave de conta
- StorageSharedKeyCredential
Geração de Assinaturas de Acesso Partilhado (SAS)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Carregamento e transferência paralelos. Tenha em atenção que BlockBlobClient.uploadData() está disponível tanto em Node.js como em browsers.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Funcionalidades, interfaces, classes ou funções disponíveis apenas em browsers

Carregamento e transferência paralelos
- BlockBlobClient.uploadBrowserData()

Pacote JavaScript

Para utilizar esta biblioteca de cliente no browser, primeiro tem de utilizar um bundler. Para obter detalhes sobre como fazê-lo, consulte a nossa documentação de agrupamento.

CORS

Se precisar de desenvolver para browsers, tem de configurar regras de Partilha de Recursos Entre Origens (CORS) para a sua conta de armazenamento. Aceda a portal do Azure e Explorador de Armazenamento do Azure, localize a sua conta de armazenamento, crie novas regras CORS para os serviços blob/queue/file/table.

Por exemplo, pode criar as seguintes definições CORS para depuração. Mas personalize cuidadosamente as definições de acordo com os 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-chave

O Armazenamento de blobs foi concebido para:

Entrega de imagens ou documentos diretamente a um browser.
Armazenamento de ficheiros para acesso distribuído.
Transmissão de áudio e vídeo.
Escrever nos ficheiros de registo.
Armazenamento de dados de cópia de segurança e restauro, recuperação após desastre e arquivo.
Armazenamento de dados para análise por um serviço no local ou alojado no Azure.

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

A conta de armazenamento utilizada através de BlobServiceClient
Um contentor na conta de armazenamento utilizada através de ContainerClient
Um blob num contentor utilizado através de BlobClient

Exemplos

Importar o pacote
Criar o cliente do serviço de blobs
Criar um novo contentor
Listar os contentores
Criar um blob ao carregar dados
Listar blobs dentro de um contentor
Transferir um blob e convertê-lo numa cadeia (Node.js)
Transferir um blob e convertê-lo numa cadeia (Browsers)

Importar o pacote

Para utilizar os clientes, importe o pacote para o seu ficheiro:

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

Em alternativa, importe seletivamente apenas os tipos de que precisa:

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

Criar o cliente do serviço de blobs

O BlobServiceClient requer um URL para o serviço de blobs e uma credencial de acesso. Também aceita opcionalmente algumas definições no options parâmetro.

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

Forma recomendada de instanciar uma BlobServiceClient

Configuração: Referência – Autorizar o acesso a blobs e filas com o Azure Active Directory a partir de uma aplicação cliente – /azure/storage/common/storage-auth-aad-app

Registar uma nova aplicação do AAD e conceder permissões para aceder ao Armazenamento do Azure em nome do utilizador com sessão iniciada
- Registar uma nova aplicação no Azure Active Directory (no azure-portal) – /azure/active-directory/develop/quickstart-register-app
- API permissions Na secção, selecione e selecione Add a permissionMicrosoft APIs.
- Selecione Azure Storage e selecione a caixa de verificação junto a user_impersonation e, em seguida, clique em Add permissions. Isto permitiria que a aplicação acedesse ao Armazenamento do Azure em nome do utilizador com sessão iniciada.
Conceder acesso aos dados de Blobs 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 do Azure, aceda à sua conta de armazenamento e atribua a função Contribuidor de Dados de Blobs de Armazenamento à aplicação do AAD registada a partir do Access control (IAM) separador (na barra de navegação do lado esquerdo da sua conta de armazenamento no azure-portal).
Configuração do ambiente para o exemplo
- Na página de descrição geral da sua Aplicação do AAD, anote e CLIENT IDTENANT ID. No separador "Certificados & Segredos", crie um segredo e anote-o.
- Certifique-se de que tem AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET como variáveis de ambiente para executar com êxito o exemplo(Pode tirar partido do processo.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
);

Veja o exemplo de Autenticação do Azure AD para obter um exemplo completo com este método.

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

com cadeia de ligação

Em alternativa, pode instanciar um BlobServiceClient com o fromConnectionString() método estático com a cadeia de ligação completa como argumento. (O cadeia de ligação pode ser obtido a partir do portal do Azure.) [APENAS DISPONÍVEL NO NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

com `StorageSharedKeyCredential`

Em alternativa, instancia um BlobServiceClient com um StorageSharedKeyCredential ao transmitir o nome da conta e a chave de conta como argumentos. (O nome da conta e a chave de conta podem ser obtidos a partir do portal do Azure.) [APENAS DISPONÍVEL NO NODE.JS RUNTIME]

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 o Token de SAS

Além disso, pode instanciar uma BlobServiceClient com assinaturas de acesso partilhado (SAS). Pode obter o token de SAS a partir do Portal do Azure ou gerar um com 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 contentor

Utilize BlobServiceClient.getContainerClient() para obter uma instância de cliente de contentor e, em seguida, crie um novo recurso de contentor.

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 contentores

Utilize BlobServiceClient.listContainers() a função para iterar os contentores, com a nova for-await-of sintaxe:

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();

Em alternativa, sem utilizar 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 de 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 um exemplo completo em contentores de iteração, veja samples/v12/typescript/src/listContainers.ts.

Criar um blob ao carregar 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 contentor

Semelhante à listagem de contentores.

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 blobs de iteração, veja samples/v12/typescript/src/listBlobsFlat.ts.

Transferir um blob e convertê-lo numa cadeia (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();

Transfira um blob e converta-o numa cadeia (Browsers).

Consulte a secção Pacote JavaScript para obter mais informações sobre como utilizar esta biblioteca no browser.

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.

Resolução de problemas

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Passos seguintes

Mais exemplos de código:

Contribuir

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

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

Impressões

Biblioteca de cliente de Blobs de Armazenamento do Azure para JavaScript – versão 12.17.0

Introdução

Ambientes atualmente suportados

Pré-requisitos

Instalar o pacote

Autenticar o cliente

Azure Active Directory

Compatibilidade

Web Workers

Diferenças entre Node.js e browsers

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

Funcionalidades, interfaces, classes ou funções disponíveis apenas em browsers

Pacote JavaScript

CORS

Conceitos-chave

Exemplos

Importar o pacote

Criar o cliente do serviço de blobs

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

com cadeia de ligação

com `StorageSharedKeyCredential`

com o Token de SAS

Criar um novo contentor

Listar os contentores

Criar um blob ao carregar dados

Listar blobs dentro de um contentor

Transferir um blob e convertê-lo numa cadeia (Node.js)

Transfira um blob e converta-o numa cadeia (Browsers).

Resolução de problemas

Passos seguintes

Contribuir

Comentários

Recursos adicionais

Biblioteca de cliente de Blobs de Armazenamento do Azure para JavaScript – versão 12.17.0

Introdução

Ambientes atualmente suportados

Pré-requisitos

Instalar o pacote

Autenticar o cliente

Azure Active Directory

Compatibilidade

Web Workers

Diferenças entre Node.js e browsers

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

Funcionalidades, interfaces, classes ou funções disponíveis apenas em browsers

Pacote JavaScript

CORS

Conceitos-chave

Exemplos

Importar o pacote

Criar o cliente do serviço de blobs

com DefaultAzureCredential do @azure/identity pacote

com cadeia de ligação

com StorageSharedKeyCredential

com o Token de SAS

Criar um novo contentor

Listar os contentores

Criar um blob ao carregar dados

Listar blobs dentro de um contentor

Transferir um blob e convertê-lo numa cadeia (Node.js)

Transfira um blob e converta-o numa cadeia (Browsers).

Resolução de problemas

Passos seguintes

Contribuir

Comentários

Recursos adicionais

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

com `StorageSharedKeyCredential`