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

Artikel
07/24/2024

Azure Storage Blob är Microsofts objektlagringslösning för molnet. Blob Storage är optimerat 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-tjänsten.

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

Hämta/ange blobtjänstegenskaper
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

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportprincip.

Förutsättningar

En Azure-prenumeration
Ett lagringskonto

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 stöder flera 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. Mer information om autentisering finns i exempel för att skapa BlobServiceClient.

Azure Active Directory-
delad nyckel
Signaturer för delad åtkomst

Azure Active Directory

Azure Blob Storage-tjänsten stöder användning av Azure Active Directory för att autentisera begäranden till dess API:er. @azure/identity-paketet innehåller en mängd olika typer av autentiseringsuppgifter som programmet kan använda för att göra detta. Mer information och exempel finns i README för @azure/identity för 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 Web Workers

Det här biblioteket är beroende av följande DOM-API:er som behöver externa polyfyller 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 har markerats med "ONLY AVAILABLE IN NODE.JS RUNTIME" eller "ONLY AVAILABLE IN BROWSERS".

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 komprimerat 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() finns 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 (Cross-Origin Resource Sharing) regler för ditt lagringskonto om du behöver utveckla för webbläsare. Gå till Azure-portalen och Azure Storage Explorer, leta reda på 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: *
Synliga rubriker: *
Maximal ålder (sekunder): 86400

Viktiga begrepp

Blob Storage är utformat för:

Hantera bilder eller dokument direkt till en webbläsare.
Lagra filer för distribuerad åtkomst.
Strömma 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 lokal eller Azure-värdbaserad tjänst.

Blob Storage erbjuder tre typer av resurser:

Det lagringskontot som används via BlobServiceClient
En container i lagringskontot som används via ContainerClient
En blob i en container som används via BlobClient

Exempel

Importera paketet
Skapa blobtjänstklienten
Skapa en ny container
Visa en lista över containrar
Skapa en blob genom att ladda upp data
Lista blobar i en container
Ladda ned en blob och konvertera den till en sträng (Node.js)
Ladda ned en blob och konvertera den till en sträng (webbläsare)

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`-paketet

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 få åtkomst till 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 göra det möjligt för programmet att komma åt 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 Storage Blob Data Contributor roll till det registrerade AAD-programmet från fliken Access control (IAM) (i navigeringsfältet till vänster i 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
);

Se Azure AD Auth-exempel för ett fullständigt exempel med den här metoden.

[Obs! Stegen ovan gäller endast för Node.js]

använda anslutningssträng

Du kan också instansiera en BlobServiceClient med hjälp av den fromConnectionString() statiska metoden med den fullständiga anslutningssträngen som argument. (Anslutningssträngen kan hämtas 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 en signatur 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 containrar

Använd funktionen BlobServiceClient.listContainers() 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å itererande 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 visa 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 i webbläsaren finns i avsnittet JavaScript Bundle.

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 på 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 med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Nästa steg

Fler kodexempel:

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Mer information om hur du konfigurerar testmiljön för lagringsbibliotek finns i storage specific guide .

visningar

Dela via

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

Komma igång

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

Förutsättningar

Installera paketet

Autentisera klienten

Azure Active Directory

Kompatibilitet

Webbarbetare

Skillnader mellan Node.js och webbläsare

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i Node.js

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i webbläsare

JavaScript-paket

CORS

Viktiga begrepp

Exempel

Importera paketet

Skapa blobtjänstklienten

med `DefaultAzureCredential` från `@azure/identity`-paketet

använda anslutningssträng

med `StorageSharedKeyCredential`

med SAS-token

Skapa en ny container

Visa en lista över containrar

Skapa en blob genom att ladda upp data

Visa en lista över blobar i en container

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

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

Felsökning

Nästa steg

Bidragande

Ytterligare resurser

Dela via

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

Komma igång

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

Förutsättningar

Installera paketet

Autentisera klienten

Azure Active Directory

Kompatibilitet

Webbarbetare

Skillnader mellan Node.js och webbläsare

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i Node.js

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i webbläsare

JavaScript-paket

CORS

Viktiga begrepp

Exempel

Importera paketet

Skapa blobtjänstklienten

med DefaultAzureCredential från @azure/identity-paketet

använda anslutningssträng

med StorageSharedKeyCredential

med SAS-token

Skapa en ny container

Visa en lista över containrar

Skapa en blob genom att ladda upp data

Visa en lista över blobar i en container

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

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

Felsökning

Nästa steg

Bidragande

Ytterligare resurser

med `DefaultAzureCredential` från `@azure/identity`-paketet

med `StorageSharedKeyCredential`