Biblioteca de clientes do Blob de Armazenamento do Azure para JavaScript – versão 12.18.0
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 estão de acordo com uma definição ou um modelo de dados específico, como texto ou dados binários.
Este projeto fornece uma biblioteca de clientes em JavaScript que facilita o consumo Armazenamento do Microsoft Azure serviço blob.
Use as bibliotecas de cliente neste pacote para:
- Obter/definir propriedades do serviço blob
- Create/Listar/Excluir Contêineres
- blobs de blocos de Create/leitura/lista/atualização/exclusão
- blobs de páginas de Create/leitura/lista/atualização/exclusão
- blobs de acréscimo de Create/leitura/lista/atualização/exclusão
Links de chave
- Código-fonte
- Pacote (npm)
- Documentação de referência da API
- Documentação do produto
- Amostras
- APIs REST do Blob de Armazenamento do Azure
Introdução
Ambientes com suporte no momento
- Versões LTS do Node.js
- Versões mais recentes do Safari, Chrome, Edge e Firefox.
Confira nossa política de suporte para mais detalhes.
Pré-requisitos
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 do terminal:
npm install @azure/storage-blob
Autenticar o cliente
O Armazenamento do Azure dá suporte a várias maneiras de autenticar. Para interagir com o serviço Armazenamento de Blobs do Azure, você precisará criar uma instância de um cliente de Armazenamento – BlobServiceClient
, ContainerClient
ouBlobClient
, por exemplo. Confira exemplos para criar o BlobServiceClient
para saber mais sobre a autenticação.
Azure Active Directory
O serviço Armazenamento de Blobs do Azure dá suporte ao uso do Azure Active Directory para autenticar solicitações em suas APIs. O @azure/identity
pacote fornece uma variedade de tipos de credenciais que seu aplicativo pode usar para fazer isso. Consulte o LEIAME para @azure/identity
obter mais detalhes e exemplos para começar.
Compatibilidade
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.
Web Workers
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á polifillá-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 armazenar dados compactados em
gzip
oudeflate
formatar e sua codificação de conteúdo for definida de acordo, o comportamento de download será diferente entre Node.js e navegadores. Em 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.
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 apenas em navegadores
- Carregamento 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. Vá para portal do Azure e 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
Principais conceitos
O Armazenamento de Blobs foi projetado para:
- Fornecimento de imagens ou de documentos diretamente a um navegador.
- Armazenamento de arquivos para acesso distribuído.
- Transmissão por streaming de áudio e vídeo.
- Gravando nos arquivo de log.
- Armazenamento de dados de 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 Blobs oferece três tipos de recursos:
- A conta de armazenamento usada por meio de
BlobServiceClient
- Um contêiner na conta de armazenamento usada por meio de
ContainerClient
- Um blob em um contêiner usado por meio de
BlobClient
Exemplos
- Importar o pacote
- Criar o cliente de serviço de blob
- Create um novo contêiner
- Listar os contêineres
- Create 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:
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 blob e uma credencial de acesso. Opcionalmente, ele também aceita algumas configurações no options
parâmetro .
com DefaultAzureCredential
do @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 – /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 azure-portal) – /azure/active-directory/develop/quickstart-register-app
API permissions
Na seção , selecioneAdd a permission
e escolhaMicrosoft APIs
.- Escolha
Azure Storage
e marque a caixa de seleção aouser_impersonation
lado de e cliqueAdd permissions
em . Isso permitiria que o aplicativo acessasse o Armazenamento do Azure em nome do usuário conectado.
Conceder acesso a 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 do Azure, acesse sua conta de armazenamento e atribua a função Colaborador de Dados de Blob de Armazenamento ao aplicativo AAD registrado na
Access control (IAM)
guia (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 visão geral do aplicativo AAD, anote o
CLIENT ID
eTENANT ID
o . Na guia "Certificados & Segredos", crie um segredo e anote-o. - 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).
- Na página de visão geral do aplicativo AAD, anote o
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 exemplo de autenticação Azure AD para obter um exemplo completo usando esse método.
[Observação - As etapas acima são apenas para Node.js]
usando cadeia de conexão
Como alternativa, você pode instanciar um BlobServiceClient
usando o fromConnectionString()
método estático com o cadeia de conexão completo como o argumento . (A cadeia de conexão pode ser obtida no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]
const { BlobServiceClient } = require("@azure/storage-blob");
const connStr = "<connection string>";
const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);
Com StorageSharedKeyCredential
Como alternativa, você cria uma instância de com um BlobServiceClient
StorageSharedKeyCredential
passando account-name e account-key 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]
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 sas (assinaturas de acesso compartilhado). Você pode obter o token SAS no 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()
a função para iterar os contêineres, 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();
Como alternativa, 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, há suporte para paginação para listagem também por meio byPage()
de :
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 sobre como iterar contêineres, consulte samples/v12/typescript/src/listContainers.ts.
Create 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.
Baixar um blob e convertê-lo em uma cadeia de caracteres (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 cadeia de caracteres (Navegadores).
Consulte a seção Pacote JavaScript 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
A habilitação do 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 log pode ser habilitado no runtime chamando setLogLevel
em @azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Próximas etapas
Mais exemplos de código:
- Exemplos de Armazenamento de Blobs (JavaScript)
- Exemplos de Armazenamento de Blobs (TypeScript)
- Casos de teste do Armazenamento de Blobs
Contribuição
Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber 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.
Azure SDK for JavaScript
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de