Creare e usare token di firma di accesso condiviso dell'account con Archiviazione BLOB di Azure e JavaScript

Articolo
08/05/2024

Questo articolo illustra come creare e usare token di firma di accesso condiviso dell'account per usare la libreria client di Archiviazione BLOB di Azure v12 per JavaScript. Dopo la connessione, il codice può operare su contenitori, BLOB e funzionalità del servizio di archiviazione BLOB.

I frammenti di codice di esempio sono disponibili in GitHub come file eseguibili Node.js.

Package (npm) | Esempi | Riferimento API | Codice sorgente della libreria | Inviare feedback

Token di firma di accesso condiviso dell'account

Un token di firma di accesso condiviso dell'account è un tipo di token di firma di accesso condiviso per la delega di accesso fornita da Archiviazione di Azure. Un token di firma di accesso condiviso dell'account fornisce l'accesso ad Archiviazione di Azure. Il token è tanto restrittivo solo in base a quanto viene definito durante la creazione. Poiché chiunque abbia il token può usarlo per accedere all'account di archiviazione, è necessario definire il token con le autorizzazioni più restrittive possibili ma che consentono comunque al token di completare le attività necessarie.

Procedure consigliate per la creazione di token includono la limitazione delle autorizzazioni:

Servizi: BLOB, file, coda, tabella
Tipi di risorsa: servizio, contenitore o oggetto
Autorizzazioni quali creazione, lettura, scrittura, aggiornamento ed eliminazione

Aggiungere le dipendenze necessarie all'applicazione

Includere le dipendenze necessarie per creare un token di firma di accesso condiviso dell'account.

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

Ottenere le variabili di ambiente per creare credenziali delle chiavi condivise

Usare il nome e la chiave dell'account di archiviazione BLOB per creare un StorageSharedKeyCredential. Questa chiave è necessaria per creare il token di firma di accesso condiviso e per usare il token di firma di accesso condiviso.

Creare un StorageSharedKeyCredential usando il nome e la chiave dell'account di archiviazione. Usare quindi StorageSharedKeyCredential per inizializzare un 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
);

Boilerplate dell'operazione asincrona

I frammenti di codice di esempio rimanenti presuppongono il codice boilerplate asincrono seguente per Node.js.

async function main() {

    const sasToken = await createAccountSas();

    await useSasToken(sasToken);
}

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

Creare un token di firma di accesso condiviso

Poiché questo token può essere usato con BLOB, code, tabelle e file, alcune impostazioni sono più ampie di quelle del BLOB.

Creare l'oggetto opzioni.

L'ambito delle capacità di un token di firma di accesso condiviso è definito da AccountSASSignatureValues.

Usare le funzioni helper seguenti fornite dall'SDK per creare i tipi di valore corretti per i valori:
- AccountSASServices.parse("btqf").toString():
  - b: BLOB
  - t: tabella
  - q: query
  - f: file
- resourceTypes: AccountSASResourceTypes.parse("sco").toString()
  - s: servizio
  - c: contenitore, ad esempio contenitore BLOB, tabella o coda
  - o: oggetto - BLOB, riga, messaggio
- Autorizzazioni: AccountSASPermissions.parse("rwdlacupi")
  - r: lettura
  - w: scrittura
  - d: eliminazione
  - l: elenco
  - f: filtro
  - a: aggiunta
  - c: creazione
  - u: aggiornamento
  - t: accesso ai tag
  - p: processo, ad esempio elaborare i messaggi in una coda
  - i: impostare criteri di immutabilità

Passare l'oggetto alla funzione generateAccountSASQueryParameters, insieme a SharedKeyCredential, per creare il token di firma di accesso condiviso.

Prima di restituire il token di firma di accesso condiviso, anteporre il delimitatore della stringa di query ?.

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}`;
}

Tenere al sicuro il token di firma di accesso condiviso fino a quando non verrà usato.

Usare il servizio BLOB con il token di firma di accesso condiviso dell'account

Per usare il token di firma di accesso condiviso dell'account, è necessario combinarlo con il nome dell'account per creare l'URI. Passare l'URI per creare blobServiceClient. Dopo aver creato blobServiceClient, è possibile usare tale client per accedere al servizio 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}`));

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Container must exist prior to running this script
const containerName = `test`;

// SAS token must have LIST permissions on container that haven't expired
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;

// Create SAS URL
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}?${sasToken}`;

async function main() {
  try {
    // create container client from SAS token
    const containerClient = new ContainerClient(sasUrl);

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }   
    
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Container and blob must exist prior to running this script
// SAS token must have READ permissions on blob that haven't expired
const containerName = `test`;
const blobName = `my-text-file.txt`;

// Create SAS URL
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}?${sasToken}`;

// Utility function to convert 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);
  });
}

async function main(){

  // Create a blob client from SAS token
  const client = new BlockBlobClient(sasUrl);

  // Get blob url
  console.log(`blob.url: ${client.url}`);

  // Download file contents
  const result = await client.download();
  const content = await streamToBuffer(result.readableStreamBody);

  // Get results
  return content.toString();
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

Il pacchetto dotenv viene usato per leggere il nome dell'account di archiviazione da un file .env. Questo file non deve essere archiviato nel controllo del codice sorgente.

Condividi tramite