Introdução ao Armazenamento de Blobs do Azure e ao JavaScript ou TypeScript

• .NET
• Java
• JavaScript
• Python
• Go

Este artigo mostra como se conectar ao Armazenamento de Blobs do Azure usando a biblioteca cliente do Armazenamento de Blobs do Azure para JavaScript. Depois de conectado, use os guias do desenvolvedor para saber como seu código pode operar em contêineres, blobs e recursos do serviço de Armazenamento de Blobs.

Se você estiver procurando começar com um exemplo completo, confira o início rápido da biblioteca de clientes para JavaScript ou TypeScript.

Referência de API | Pacote (npm) | Código-fonte da biblioteca | Amostras | Enviar comentários

Pré-requisitos

• Assinatura do Azure - criar uma gratuitamente
• Conta de armazenamento do Azure – criar uma conta de armazenamento
• Node.js LTS
• TypeScript, se aplicável
• Para aplicativos cliente (navegador), você precisa de ferramentas de agrupamento.

Configurar o seu projeto

Esta seção explica como preparar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure para JavaScript.

Abra um prompt de comando e navegue até a pasta do seu projeto. Altere <project-directory> para o nome da pasta:

cd <project-directory>

Se você ainda não tiver um arquivo package.json no diretório, inicialize o projeto para criar o arquivo:

npm init -y

No diretório do projeto, instale pacotes para as bibliotecas de cliente do Armazenamento de Blobs do Azure e do Azure Identity usando os comandos npm install ou yarn add. O pacote @azure/identity é necessário para conexões sem senha com os serviços do Azure.

JavaScript

npm install @azure/storage-blob @azure/identity

TypeScript

npm install typescript @azure/storage-blob @azure/identity

Autorizar o acesso e se conectar ao Armazenamento de Blobs

Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância da classe BlobServiceClient. Esse objeto é seu ponto de partida para interagir com os recursos de dados no nível da conta de armazenamento. Você pode usá-lo para operar na conta de armazenamento e nos respectivos contêineres. Você também pode usar o cliente de serviço para criar clientes de contêiner ou clientes de blob, dependendo do recurso com o qual você precisa trabalhar.

Para saber mais sobre como criar e gerenciar objetos clientes, inclusive as melhores práticas, confira Criar e gerenciar objetos de cliente que interagem com recursos de dados.

Autorize um objeto BlobServiceClient usando um token de autorização do Microsoft Entra, uma chave de acesso de conta ou uma SAS (assinatura de acesso compartilhado). Para otimizar a segurança, a Microsoft recomenda o uso do Microsoft Entra ID com identidades gerenciadas para autorizar solicitações contra dados de blob. Para obter mais informações, consulte Autorizar o acesso a blobs usando o Microsoft Entra ID.

Microsoft Entra ID (recomendado)

Para autorizar com a ID do Microsoft Entra, você precisará usar uma entidade de segurança. O tipo de entidade de segurança de que você precisa depende do local em que o aplicativo é executado. Use a tabela a seguir como guia:

O local em que o aplicativo é executado	Entidade de segurança	Diretrizes
Computador local (desenvolvimento e teste)	Entidade de serviço	Para saber como registrar o aplicativo, configurar um grupo do Microsoft Entra, atribuir funções e configurar variáveis de ambiente, confira Autorizar o acesso usando entidades de serviço do desenvolvedor
Computador local (desenvolvimento e teste)	Identidade do usuário	Para saber como configurar um grupo do Microsoft Entra, atribuir funções e entrar no Azure, confira Autorizar o acesso usando credenciais de desenvolvedor
Hospedada no Azure	Identidade gerenciada	Para saber como habilitar a identidade gerenciada e atribuir funções, confira Autorizar o acesso de aplicativos hospedados no Azure usando uma identidade gerenciada
Hospedado fora do Azure (por exemplo, aplicativos locais)	Entidade de serviço	Para saber como registrar o aplicativo, atribuir funções e configurar variáveis de ambiente, confira Autorizar o acesso em aplicativos locais usando uma entidade de serviço de aplicativo

Autorizar o acesso usando DefaultAzureCredential

Uma maneira fácil e segura de autorizar o acesso e se conectar ao Armazenamento de Blobs é obter um token OAuth criando uma instância de DefaultAzureCredential. Em seguida, use essa credencial para criar um objeto BlobServiceClient.

O exemplo a seguir cria um objeto BlobServiceClient usando DefaultAzureCredential:

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

Este exemplo de código pode ser usado para projetos JavaScript ou TypeScript.

Token SAS

Para usar um token de SAS (assinatura de acesso compartilhado), acrescente o token à cadeia de caracteres de URL da conta separada por um delimitador ?. Em seguida, crie um objeto BlobServiceClient com o URL.

const accountName = "<account-name>";
const sasToken = "<sas-token>";
const accountURL = `https://${accountName}.blob.core.windows.net?${sasToken}`;
const blobServiceClient = new BlobServiceClient(accountURL);

Este exemplo de código pode ser usado para projetos JavaScript ou TypeScript.

Para saber mais sobre como gerar e gerenciar tokens SAS, confira os seguintes artigos:

• Conceder acesso limitado aos recursos de Armazenamento do Azure usando as SAS (assinaturas de acesso compartilhado)
• Criar uma SAS de conta com o JavaScript
• Crie um serviço SAS com JavaScript
• Criar uma SAS de delegação de usuário com o JavaScript

Observação

Para os cenários em que as assinaturas de acesso compartilhado (SAS) são utilizadas, a Microsoft recomenda o uso de uma SAS de delegação de usuário. Uma SAS de delegação de usuário é protegida por credenciais do Microsoft Entra em vez da chave da conta.

Chave de conta

Para usar uma chave compartilhada da conta de armazenamento, forneça a chave como uma cadeia de caracteres e inicialize um objeto BlobServiceClient.

const credential = new StorageSharedKeyCredential(accountName, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  credential
);

Este exemplo de código pode ser usado para projetos JavaScript ou TypeScript.

Você também pode criar um objeto BlobServiceClient usando uma cadeia de conexão.

const blobServiceClient = BlobServiceClient.fromConnectionString(connectionString);

Para obter informações sobre como obter chaves de conta e diretrizes de melhores práticas para gerenciar e proteger corretamente suas chaves, consulte Gerenciar chaves de acesso da conta de armazenamento.

Importante

A chave de acesso da conta deve ser usada com cautela. Se a chave de acesso da conta for perdida ou colocada acidentalmente em um local inseguro, o serviço poderá ficar vulnerável. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential fornece recursos e benefícios de segurança avançados e é a abordagem recomendada para gerenciar a autorização para os serviços do Azure.

Compilar o aplicativo

À medida que você cria aplicativos para trabalhar com recursos de dados no Armazenamento de Blobs do Azure, seu código interage principalmente com três tipos de recursos: contas de armazenamento, contêineres e blobs. Para saber mais sobre esses tipos de recursos, como eles se relacionam entre si e como os aplicativos interagem com os recursos, confira Entender como os aplicativos interagem com os recursos de dados do Armazenamento de Blobs.

Os guias a seguir mostram como acessar dados e executar ações específicas usando a biblioteca de clientes do Armazenamento do Microsoft Azure para JavaScript:

Guia	Descrição
Configurar uma política de repetição	Implementar políticas de repetição para operações do cliente.
Copiar blobs	Copie um blob de uma localização para outra.
Criar um contêiner	Criar contêineres de blob.
Criar uma SAS de delegação de usuário	Crie uma delegação de usuário SAS para um contêiner ou blob.
Criar e gerenciar concessões de blob	Estabeleça e gerencie um bloqueio em um blob.
Criar e gerenciar concessões de contêiner	Estabeleça e gerencie um bloqueio em um contêiner.
Excluir e restauração	Excluir blobs e restaurar blobs removidos com a exclusão temporária.
Excluir e restaurar contêineres	Excluir contêineres e restaurar contêineres removidos com a exclusão temporária.
Baixar blobs	Baixe blobs usando cadeias de caracteres, fluxos e caminhos de arquivo.
Encontrar blobs usando marcas	Defina e recupere marcas e use as marcas para localizar blobs.
Listar blobs	Liste blobs de maneiras diferentes.
Listar contêineres	Liste os contêineres em uma conta e as diversas opções disponíveis para personalizar uma listagem.
Gerenciar propriedades e metadados (blobs)	Obtenha e defina as propriedades e metadados dos blobs.
Gerenciar propriedades e metadados (contêineres)	Obtenha e defina as propriedades e metadados dos contêineres.
Ajuste de desempenho para transferências de dados	Otimizar o desempenho para operações de transferência de dados.
Definir ou alterar o nível de acesso de um blob	Defina ou altere a camada de acesso para um blob de blocos.
Carregar blobs	Saiba como carregar blobs usando cadeias de caracteres, fluxos, caminhos de arquivo e outros métodos.