Erstellen und Verwenden von Konto-SAS-Token mit Azure Blob Storage und JavaScript

Artikel
09/21/2023

In diesem Artikel erfahren Sie, wie Sie in der Azure Blob Storage-Clientbibliothek v12 für JavaScript ein Konto-SAS-Token erstellen. Nach der Verbindung kann Ihr Code Container, Blobs und Features des Blob Storage-Diensts verwenden.

Die Beispielcodeausschnitte sind in GitHub als ausführbare Node.js-Dateien verfügbar.

Paket (npm) | Beispiele | API-Dokumentation | Bibliothekquellcode | Feedback einreichen

Konto-SAS-Token

Ein Konto-SAS-Token ist ein von Azure Storage bereitgestellter SAS-Tokentyp für die Zugriffsdelegierung. Ein Konto-SAS-Token bietet Zugriff auf Azure Storage. Das Token ist nur so restriktiv, wie Sie es beim Erstellen definieren. Da jede Person mit dem Token auf Ihr Azure Storage-Konto zugreifen kann, sollten Sie das Token mit den restriktivsten Berechtigungen definieren, mit denen mithilfe des Tokens die erforderlichen Aufgaben ausgeführt werden können.

Bewährte Methoden für die Tokenerstellung sehen eingeschränkte Berechtigungen vor:

Dienste: Blob, Datei, Warteschlange, Tabelle
Ressourcentypen: Dienst, Container oder Objekt
Berechtigungen wie Erstellen, Lesen, Schreiben, Aktualisieren und Löschen

Hinzufügen erforderlicher Abhängigkeiten zu Ihrer Anwendung

Schließen Sie die erforderlichen Abhängigkeiten ein, um ein Konto-SAS-Token zu erstellen.

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

Abrufen von Umgebungsvariablen zum Erstellen von Anmeldeinformationen mit gemeinsam verwendetem Schlüssel

Verwenden Sie den Blob Storage-Kontonamen und -Schlüssel, um eine Instanz von StorageSharedKeyCredential zu erstellen. Dieser Schlüssel ist erforderlich, um das SAS-Token zu erstellen und zu verwenden.

Erstellen Sie mithilfe des Speicherkontonamens und des Kontoschlüssels ein storageSharedKeyCredential. Verwenden Sie dann den StorageSharedKeyCredential, um einen BlobServiceClient zu initialisieren.

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

Codebaustein für asynchrone Vorgänge

Die verbleibenden Beispielcodeschnipsel gehen vom folgenden Codebaustein für asynchrone Vorgänge für Node.js aus.

async function main() {

    const sasToken = await createAccountSas();

    await useSasToken(sasToken);
}

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

Erstellen eines SAS-Tokens

Da dieses Token mit Blobs, Warteschlangen, Tabellen und Dateien verwendet werden kann, sind einige der Einstellungen weiter gefasst als nur die Optionen für Blobs.

Erstellen Sie das Optionsobjekt.

Der Umfang der Möglichkeiten eines SAS-Tokens wird von accountSASSignatureValues bestimmt.

Erstellen Sie mithilfe der folgenden Hilfsfunktionen im SDK die richtigen Werttypen für die Werte:
- AccountSASServices.parse("btqf").toString():
  - b: Blob
  - t: Tabelle
  - q: query (Abfrage)
  - f: file (Datei)
- resourceTypes: AccountSASResourceTypes.parse("sco").toString()
  - s: service (Dienst)
  - c: container – z. B. Blobcontainer, Tabelle oder Warteschlange
  - o: Objekt – Blob, Zeile, Nachricht
- permissions: AccountSASPermissions.parse("rwdlacupi")
  - r: read (Lesen)
  - w: write (Schreiben)
  - d: delete (Löschen)
  - l: Liste
  - f: Filter
  - a: add (Hinzufügen)
  - c: create (Erstellen)
  - u: update (Aktualisieren)
  - t: Tagzugriff
  - p: Prozess – z. B. Verarbeiten von Nachrichten in einer Warteschlange
  - i: set immutability policy (Unveränderlichkeitsrichtlinie festlegen)

Übergeben Sie das Objekt generateAccountSASQueryParameters zusammen mit SharedKeyCredentials an die Funktion, um das SAS-Token zu erstellen.

Bevor das SAS-Token zurückgegeben wird, stellen Sie das Trennzeichen für die Abfragezeichenfolge ? voran.

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

Sichern Sie das SAS-Token ab, bis es verwendet wird.

Verwenden des Blob-Diensts mit einem Konto-SAS-Token

Um das Konto-SAS-Token verwenden zu können, müssen Sie es zum Erstellen des URI mit dem Kontonamen kombinieren. Übergeben Sie den URI, um blobServiceClient zu erstellen. Sobald Sie über blobServiceClient verfügen, können Sie diesen Client verwenden, um auf Ihre Blob-Dienst-Instanz zuzugreifen.

// 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));

Das Paket dotenv wird verwendet, um den Namen Ihres Speicherkontos aus einer .env-Datei zu lesen. Diese Datei sollte nicht in die Quellcodeverwaltung eingecheckt werden.