Criar e usar tokens SAS de conta com Armazenamento de Blobs do Azure e JavaScript

  • Artigo

Este artigo mostra como criar e usar tokens SAS de conta para usar a biblioteca de clientes do Armazenamento de Blobs do Azure v12 para JavaScript. Após se conectar, seu código pode operar em contêineres, blobs e recursos do serviço de Armazenamento de Blobs.

Os snippets de código de exemplo estão disponíveis no GitHub como arquivos Node.js executáveis.

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

Tokens SAS de conta

Um token SAS de conta é um tipo de token SAS para delegação de acesso fornecida pelo Armazenamento do Microsoft Azure. Um token SAS de conta fornece acesso ao Armazenamento do Microsoft Azure. O token é tão restritivo quanto você o define ao criá-lo. Como qualquer pessoa com o token pode usá-lo para acessar sua conta de Armazenamento, você deve definir o token com as permissões mais restritivas que ainda permitem que o token conclua as tarefas necessárias.

As práticas recomendadas para a criação de token incluem a limitação de permissões:

  • Serviços: blob, arquivo, fila, tabela
  • Tipos de recurso: serviço, contêiner ou objeto
  • Permissões como criar, ler, gravar, atualizar e excluir

Adicionar dependências necessárias ao aplicativo

Inclua as dependências necessárias para criar um token SAS de conta.

const { 
    BlobServiceClient, 
    generateAccountSASQueryParameters, 
    AccountSASPermissions, 
    AccountSASServices,
    AccountSASResourceTypes,
    StorageSharedKeyCredential,
    SASProtocol 
} = require('@azure/storage-blob');
require('dotenv').config()

Obter variáveis de ambiente para criar credencial de chave compartilhada

Use o nome e a chave da conta de Armazenamento de Blobs para criar um StorageSharedKeyCredential. Essa chave é necessária para criar o token SAS e usar o token SAS.

Crie um StorageSharedKeyCredential usando o nome da conta de armazenamento e a chave de conta. Use o StorageSharedKeyCredential para inicializar um BlobServiceClient.

const constants = {
    accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
    accountKey: process.env.AZURE_STORAGE_ACCOUNT_KEY
};
const sharedKeyCredential = new StorageSharedKeyCredential(
    constants.accountName,
    constants.accountKey
);

Texto clichê de operação assíncrona

Os snippets de código de exemplo restantes assumem o seguinte código clichê assíncrono para Node.js.

async function main() {

    const sasToken = await createAccountSas();

    await useSasToken(sasToken);
}

main()
    .then(() => {
        console.log(`done`);
    }).catch((ex) => {
        console.log(`Error: ${ex.message}`)
    });

Criar um token SAS

Como esse token pode ser usado com blobs, filas, tabelas e arquivos, algumas das configurações são mais amplas do que apenas opções de blob.

  1. Crie o objeto options.

    O escopo das habilidades de um token SAS é definido pelo AccountSASSignatureValues.

    Use as seguintes funções auxiliares fornecidas pelo SDK para criar os tipos de valor corretos para os valores:

  2. Passe o objeto para a função generateAccountSASQueryParameters, juntamente com o SharedKeyCredential, para criar o token SAS.

    Antes de retornar o token SAS, preceda o delimitador da cadeia de caracteres de consulta, ?.

    async function createAccountSas() {

    const sasOptions = {

        services: AccountSASServices.parse("btqf").toString(),          // blobs, tables, queues, files
        resourceTypes: AccountSASResourceTypes.parse("sco").toString(), // service, container, object
        permissions: AccountSASPermissions.parse("rwdlacupi"),          // permissions
        protocol: SASProtocol.Https,
        startsOn: new Date(),
        expiresOn: new Date(new Date().valueOf() + (10 * 60 * 1000)),   // 10 minutes
    };

    const sasToken = generateAccountSASQueryParameters(
        sasOptions,
        sharedKeyCredential 
    ).toString();

    console.log(`sasToken = '${sasToken}'\n`);

    // prepend sasToken with `?`
    return (sasToken[0] === '?') ? sasToken : `?${sasToken}`;
}

  3. Proteja o token SAS até que ele seja usado.

Usar o serviço Blob com o token SAS da conta

Para usar o token SAS da conta, você precisa combiná-lo com o nome da conta para criar o URI. Passe o URI para criar o blobServiceClient. Depois de ter o blobServiceClient, você poderá usar esse cliente para acessar seu serviço Blob.

// connect-with-sas-token.js
const { BlobServiceClient } = require('@azure/storage-blob');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
if (!accountName) throw Error('Azure Storage accountName not found');
if (!sasToken) throw Error('Azure Storage accountKey not found');

const blobServiceUri = `https://${accountName}.blob.core.windows.net`;

// https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN
const blobServiceClient = new BlobServiceClient(
  `${blobServiceUri}?${sasToken}`,
  null
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

O pacote dotenv é usado para ler o nome da conta de armazenamento de um arquivo .env. Esse arquivo não deve ser verificado no controle do código-fonte.

Confira também