Guia de início rápido: biblioteca de cliente do Armazenamento de Blobs do Azure para Node.js com TypeScript

Introdução à biblioteca de cliente do Armazenamento de Blobs do Azure para Node.js com TypeScript para gerenciar blobs e contêineres.

Neste artigo, siga as etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

Referência | da API Pacote de código-fonte | da biblioteca (npm)Exemplos |

Pré-requisitos

• Conta do Azure com uma subscrição ativa - crie uma conta gratuitamente
• Conta de Armazenamento do Azure - Criar uma conta de armazenamento
• Node.js LTS
• TypeScript

Configuração

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para Node.js.

Criar o projeto Node.js

Crie um aplicativo TypeScript chamado blob-quickstart.

1. Em uma janela do console (como cmd, PowerShell ou Bash), crie um novo diretório para o projeto:

   mkdir blob-quickstart
   

2. Alterne para o diretório blob-quickstart recém-criado:

   cd blob-quickstart
   

3. Crie um arquivo package.json :

   npm init -y
   

4. Abra o projeto no Visual Studio Code:

   code .
   

5. Edite o arquivo package.json para adicionar as seguintes propriedades para oferecer suporte ao ESM com TypeScript:

   "type": "module",
   

Instalar os pacotes

No diretório do projeto, instale os seguintes pacotes usando o npm install comando.

1. Instale o pacote npm do Armazenamento do Azure:

   npm install @azure/storage-blob
   

2. Instale outras dependências usadas neste início rápido:

   npm install uuid dotenv @types/node @types/uuid
   

3. Crie um tsconfig.json arquivo no diretório do projeto com o seguinte conteúdo.

   {
       "compilerOptions": {
         "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
         "module": "ESNext",                                /* Specify what module code is generated. */
         "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
         "outDir": "dist",                                   /* Specify an output folder for all emitted files. */
         "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
         "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
         "strict": true,                                      /* Enable all strict type-checking options. */
         "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
       }
     }
   

Modelo de objeto

O armazenamento de Blob do Azure é otimizado para armazenar grandes quantidades 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 particular, como texto ou dados binários. O armazenamento de Blob oferece três tipos de recursos:

• A conta de armazenamento
• Um contêiner na conta de armazenamento
• Uma bolha no recipiente

O diagrama seguinte mostra a relação entre estes recursos.

Use as seguintes classes JavaScript para interagir com esses recursos:

• BlobServiceClient: A BlobServiceClient classe permite manipular recursos de Armazenamento do Azure e contêineres de blob.
• ContainerClient: A ContainerClient classe permite manipular contêineres de Armazenamento do Azure e seus blobs.
• BlobClient: A BlobClient classe permite manipular blobs de Armazenamento do Azure.

Exemplos de código

Estes trechos de código de exemplo mostram como executar as seguintes tarefas com a biblioteca de cliente do Armazenamento de Blobs do Azure para JavaScript:

• Autenticar no Azure e autorizar o acesso a dados de blob
• Criar um contêiner
• Carregar blobs para um contêiner
• Listar os blobs em um contêiner
• Baixar blobs
• Eliminar um contentor

O código de exemplo também está disponível no GitHub.

Autenticar no Azure e autorizar o acesso a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. Usar a DefaultAzureCredential classe fornecida pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código, incluindo o Armazenamento de Blob.

Você também pode autorizar solicitações para o Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, esta abordagem deve ser utilizada com precaução. Os desenvolvedores devem ser diligentes para nunca expor a chave de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso é capaz de autorizar solicitações contra a conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave da conta para permitir autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

az storage account show-connection-string --name "<your-storage-account-name>"

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

const connectionString = process.env.AZURE_STORAGE_CONNECTION_STRING as string; 
if (!connectionString) throw Error('Azure Storage connectionString not found');

Criar um contentor

Crie um novo contêiner na conta de armazenamento. O exemplo de código a seguir usa um objeto BlobServiceClient e chama o método getContainerClient para obter uma referência a um contêiner. Em seguida, o código chama o método create para realmente criar o contêiner em sua conta de armazenamento.

Adicione este código ao final do try bloco:

  const containerName = 'quickstart' + uuidv4();

  console.log('\nCreating container...');
  console.log('\t', containerName);

  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse: ContainerCreateResponse = await containerClient.create();
  console.log(
    `Container was created successfully.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
  );

Para saber mais sobre como criar um contêiner e explorar mais exemplos de código, consulte Criar um contêiner de blob com JavaScript.

Carregar blobs para um contêiner

Carregue um blob para o contentor. O código a seguir obtém uma referência a um objeto BlockBlobClient chamando o método getBlockBlobClient no ContainerClient da seção Criar um contêiner .

O código carrega os dados da cadeia de caracteres de texto para o blob chamando o método de upload .

Adicione este código ao final do try bloco:

  const blobName = 'quickstart' + uuidv4(); + '.txt';
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  console.log(
    `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
  );

  const data = 'Hello, World!';
  const uploadBlobResponse: BlockBlobUploadResponse = await blockBlobClient.upload(data, data.length);
  console.log(
    `Blob was uploaded successfully. requestId: ${uploadBlobResponse.requestId}`
  );

Para saber mais sobre como carregar blobs e explorar mais exemplos de código, consulte Carregar um blob com JavaScript.

Listar os blobs num contentor

Liste os blobs no contentor. O código a seguir chama o método listBlobsFlat . Nesse caso, apenas um blob está no contêiner, portanto, a operação de listagem retorna apenas esse blob.

Adicione este código ao final do try bloco:

  console.log('\nListing blobs...');

  for await (const blob of containerClient.listBlobsFlat()) {
    const tempBlockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blob.name);

    console.log(
      `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
    );
  }

Para saber mais sobre como listar blobs e explorar mais exemplos de código, consulte Listar blobs com JavaScript.

Transferir blobs

Baixe o blob e exiba o conteúdo. O código a seguir chama o método de download para baixar o blob.

Adicione este código ao final do try bloco:

  const offset = 0;         // start at beginning
  const length = undefined; // read all

  const downloadBlockBlobResponse: BlobDownloadResponseParsed = await blockBlobClient.download(offset, length);
  console.log('\nDownloaded blob content...');
  console.log(
    '\t',
    await streamToText(downloadBlockBlobResponse.readableStreamBody as NodeJS.ReadableStream)
  );

O código a seguir converte um fluxo de volta em uma cadeia de caracteres para exibir o conteúdo.

Adicione este código após a main função:

// Convert stream to text
async function streamToText(readable: NodeJS.ReadableStream): Promise<string> {
  readable.setEncoding('utf8');
  let data = '';
  for await (const chunk of readable) {
    data += chunk;
  }
  return data;
}

Para saber mais sobre como baixar blobs e explorar mais exemplos de código, consulte Baixar um blob com JavaScript.

Eliminar um contentor

Exclua o contêiner e todos os blobs dentro do contêiner. O código a seguir limpa os recursos criados pelo aplicativo removendo todo o contêiner usando o método delete .

Adicione este código ao final do try bloco:

  console.log('\nDeleting container...');

  const deleteContainerResponse: ContainerDeleteResponse = await containerClient.delete();
  console.log(
    'Container was deleted successfully. requestId: ',
    deleteContainerResponse.requestId
  );

Para saber mais sobre como excluir um contêiner e explorar mais exemplos de código, consulte Excluir e restaurar um contêiner de blob com JavaScript.

Executar o código

1. A partir de um terminal do Visual Studio Code, crie o aplicativo.

   tsc
   

2. Executar a aplicação.

   node dist/index.js
   

3. A saída do aplicativo é semelhante ao exemplo a seguir:

   Azure Blob storage - JavaScript quickstart sample
   
   Creating container...
       quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da
   
   Uploading to Azure Storage as blob:
       quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt
   
   Listing blobs...
       quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt
   
   Downloaded blob content...
       Hello, World!
   
   Deleting container...
   Done
   

Percorra o código no depurador e verifique o portal do Azure durante todo o processo. Verifique se o contêiner está sendo criado. Você pode abrir o blob dentro do contêiner e visualizar o conteúdo.

Clean up resources (Limpar recursos)

1. Quando terminar este início rápido, exclua o blob-quickstart diretório.
2. Se você tiver terminado de usar seu recurso de Armazenamento do Azure, use a CLI do Azure para remover o recurso de Armazenamento.

Próximo passo