Azure Storage Blob-klientbibliotek för JavaScript – version 12.17.0

  • Artikel

Azure Storage Blob är Microsofts objektlagringslösning för molnet. Blob Storage är optimerad för lagring av enorma mängder ostrukturerade data. Ostrukturerade data är data som inte följer en viss datamodell eller definition, till exempel text eller binära data.

Det här projektet tillhandahåller ett klientbibliotek i JavaScript som gör det enkelt att använda Microsoft Azure Storage Blob Service.

Använd klientbiblioteken i det här paketet för att:

  • Hämta/ange egenskaper för blobtjänsten
  • Skapa/lista/ta bort containrar
  • Skapa/läsa/lista/uppdatera/ta bort blockblobar
  • Skapa/läsa/lista/uppdatera/ta bort sidblobar
  • Skapa/läsa/lista/uppdatera/ta bort tilläggsblobar

Nyckellänkar

Komma igång

Miljöer som stöds för närvarande

Mer information finns i vår supportpolicy .

Förutsättningar

Installera paketet

Det bästa sättet att installera Azure Storage Blob-klientbiblioteket för JavaScript är att använda npm-pakethanteraren. Skriv följande i ett terminalfönster:

npm install @azure/storage-blob

Autentisera klienten

Azure Storage har stöd för flera olika sätt att autentisera. För att interagera med Azure Blob Storage-tjänsten måste du skapa en instans av en Storage-klient – BlobServiceClient, ContainerClienteller BlobClient till exempel. Se exempel för att skapa BlobServiceClientför att lära dig mer om autentisering.

Azure Active Directory

Tjänsten Azure Blob Storage stöder användning av Azure Active Directory för att autentisera begäranden till dess API:er. Paketet @azure/identity innehåller en mängd olika typer av autentiseringsuppgifter som ditt program kan använda för att göra detta. Mer information och exempel finns i README för @azure/identity att komma igång.

Kompatibilitet

Det här biblioteket är kompatibelt med Node.js och webbläsare och verifieras mot LTS Node.js versioner (>=8.16.0) och de senaste versionerna av Chrome, Firefox och Edge.

Webbarbetare

Det här biblioteket kräver att vissa DOM-objekt är globalt tillgängliga när de används i webbläsaren, vilket webbarbetare inte gör tillgängliga som standard. Du måste polyfylla dessa för att det här biblioteket ska fungera i webbarbetare.

Mer information finns i vår dokumentation för att använda Azure SDK för JS i Webbarbetare

Det här biblioteket är beroende av följande DOM-API:er som behöver externa polyfiller som läses in när de används i webbarbetare:

Skillnader mellan Node.js och webbläsare

Det finns skillnader mellan Node.js- och webbläsarkörning. När du kommer igång med det här biblioteket bör du vara uppmärksam på API:er eller klasser som markerats med "ENDAST TILLGÄNGLIGT I NODE.JS RUNTIME" eller "ENDAST TILLGÄNGLIGT I WEBBLÄSARE".

  • Om en blob innehåller komprimerade data i gzip eller deflate format och dess innehållskodning anges i enlighet med detta skiljer sig nedladdningsbeteendet mellan Node.js och webbläsare. I Node.js kommer lagringsklienter att ladda ned bloben i sitt komprimerade format, medan data i webbläsare laddas ned i avkomprimerat format.
Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i Node.js
  • Auktorisering av delad nyckel baserat på kontonamn och kontonyckel
    • StorageSharedKeyCredential
  • Generering av signatur för delad åtkomst (SAS)
    • generateAccountSASQueryParameters()
    • generateBlobSASQueryParameters()
  • Parallell uppladdning och nedladdning. Observera att BlockBlobClient.uploadData() är tillgängligt i både Node.js och webbläsare.
    • BlockBlobClient.uploadFile()
    • BlockBlobClient.uploadStream()
    • BlobClient.downloadToBuffer()
    • BlobClient.downloadToFile()
Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i webbläsare
  • Parallell uppladdning och nedladdning
    • BlockBlobClient.uploadBrowserData()

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

CORS

Du måste konfigurera CORS-regler (Cross-Origin Resource Sharing) för ditt lagringskonto om du behöver utveckla för webbläsare. Gå till Azure Portal och Azure Storage Explorer, leta upp ditt lagringskonto, skapa nya CORS-regler för blob/kö/fil/tabelltjänster.

Du kan till exempel skapa följande CORS-inställningar för felsökning. Men anpassa inställningarna noggrant enligt dina krav i produktionsmiljön.

  • Tillåtet ursprung: *
  • Tillåtna verb: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Tillåtna rubriker: *
  • Exponerade rubriker: *
  • Maximal ålder (sekunder): 86400

Viktiga begrepp

Blobblagring är utformat för att:

  • Leverera bilder eller dokument direkt till en webbläsare.
  • Lagra filer för distribuerad åtkomst.
  • Direktuppspelning av video och ljud.
  • Skriva till loggfiler.
  • Lagra data för säkerhetskopiering och återställning, haveriberedskap och arkivering.
  • Lagra data för analys av en tjänst som kan vara lokal eller Azure-värdbaserad.

I blobblagringen finns tre typer av resurser:

  • Lagringskontot som används viaBlobServiceClient
  • En container i lagringskontot som används via ContainerClient
  • En blob i en container som används via BlobClient

Exempel

Importera paketet

Om du vill använda klienterna importerar du paketet till filen:

const AzureStorageBlob = require("@azure/storage-blob");

Alternativt kan du selektivt importera endast de typer som du behöver:

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

Skapa blobtjänstklienten

BlobServiceClient kräver en URL till blobtjänsten och en åtkomstautentiseringsuppgift. Du kan också välja att acceptera vissa inställningar i parametern options .

med DefaultAzureCredential från @azure/identity paket

Rekommenderat sätt att instansiera en BlobServiceClient

Installation: Referens – Auktorisera åtkomst till blobar och köer med Azure Active Directory från ett klientprogram – /azure/storage/common/storage-auth-aad-app

  • Registrera ett nytt AAD-program och ge behörighet att komma åt Azure Storage för den inloggade användarens räkning

    • Registrera ett nytt program i Azure Active Directory (i azure-portalen) – /azure/active-directory/develop/quickstart-register-app
    • I avsnittet API permissions väljer du Add a permission och väljer Microsoft APIs.
    • Välj Azure Storage och markera kryssrutan bredvid user_impersonation och klicka sedan på Add permissions. Detta skulle ge programmet åtkomst till Azure Storage för den inloggade användarens räkning.

  • Bevilja åtkomst till Azure Blob-data med RBAC i Azure-portalen

    • RBAC-roller för blobar och köer – /azure/storage/common/storage-auth-aad-rbac-portal.
    • I Azure-portalen går du till ditt lagringskonto och tilldelar rollen Storage Blob Data-deltagare till det registrerade AAD-programmet från Access control (IAM) fliken (i det vänstra navigeringsfältet för ditt lagringskonto i azure-portalen).

  • Miljökonfiguration för exemplet

    • På översiktssidan för ditt AAD-program noterar du CLIENT ID och TENANT ID. På fliken "Certifikat & hemligheter" skapar du en hemlighet och noterar den nedåt.
    • Kontrollera att du har AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET som miljövariabler för att köra exemplet (Kan utnyttja process.env).
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

Ett fullständigt exempel med den här metoden finns i exemplet Azure AD Auth.

[Obs! Ovanstående steg gäller endast för Node.js]

med anslutningssträng

Du kan också instansiera en BlobServiceClient med hjälp av den fromConnectionString() statiska metoden med den fullständiga anslutningssträng som argument. (Du kan hämta anslutningssträng från Azure-portalen.) [ENDAST TILLGÄNGLIGT I NODE.JS RUNTIME]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

Med StorageSharedKeyCredential

Du kan också instansiera en BlobServiceClient med en StorageSharedKeyCredential genom att skicka kontonamn och kontonyckel som argument. (Kontonamnet och kontonyckeln kan hämtas från Azure-portalen.) [ENDAST TILLGÄNGLIGT I NODE.JS RUNTIME]

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential
);

med SAS-token

Du kan också instansiera en BlobServiceClient med signaturer för delad åtkomst (SAS). Du kan hämta SAS-token från Azure-portalen eller generera en med hjälp av generateAccountSASQueryParameters().

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

Skapa en ny container

Använd BlobServiceClient.getContainerClient() för att hämta en containerklientinstans och skapa sedan en ny containerresurs.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a container
  const containerName = `newcontainer${new Date().getTime()}`;
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse = await containerClient.create();
  console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}

main();

Visa en lista över containrarna

Använd BlobServiceClient.listContainers() funktionen för att iterera containrarna med den nya for-await-of syntaxen:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

Alternativt utan att använda for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let iter = blobServiceClient.listContainers();
  let containerItem = await iter.next();
  while (!containerItem.done) {
    console.log(`Container ${i++}: ${containerItem.value.name}`);
    containerItem = await iter.next();
  }
}

main();

Dessutom stöds sidnumrering även för listning via byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
    if (response.containerItems) {
      for (const container of response.containerItems) {
        console.log(`Container ${i++}: ${container.name}`);
      }
    }
  }
}

main();

Ett fullständigt exempel på iterering av containrar finns i samples/v12/typescript/src/listContainers.ts.

Skapa en blob genom att ladda upp data

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  const content = "Hello world!";
  const blobName = "newblob" + new Date().getTime();
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);
  const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
  console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}

main();

Visa en lista över blobar i en container

Liknar att lista containrar.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  let i = 1;
  let blobs = containerClient.listBlobsFlat();
  for await (const blob of blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

main();

Ett fullständigt exempel på iterering av blobar finns i samples/v12/typescript/src/listBlobsFlat.ts.

Ladda ned en blob och konvertera den till en sträng (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [Node.js only] A helper method used to read 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);
    });
  }
}

main();

Ladda ned en blob och konvertera den till en sträng (webbläsare).

Mer information om hur du använder det här biblioteket finns i avsnittet JavaScript-paket i webbläsaren.

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Ett fullständigt exempel på enkla scenarier finns i samples/v12/typescript/src/sharedKeyAuth.ts.

Felsökning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Loggning kan också aktiveras vid körning genom att anropa setLogLevel i @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Nästa steg

Fler kodexempel:

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.

Mer information om hur du konfigurerar testmiljön för lagringsbibliotek finns i guiden Lagringsspecifik .

Visningar