Klientská knihovna Azure Storage Blob pro JavaScript – verze 12.24.0

Článek
07/24/2024

Azure Storage Blob je řešení úložiště objektů od Microsoftu pro cloud. Úložiště objektů blob je optimalizované pro ukládání obrovských objemů nestrukturovaných dat. Nestrukturovaná data jsou data, která nedodržují konkrétní datový model nebo definici, jako jsou textová nebo binární data.

Tento projekt poskytuje klientskou knihovnu v JavaScriptu, která usnadňuje využívání služby Microsoft Azure Storage Blob Service.

Klientské knihovny v tomto balíčku slouží k:

Získání nebo nastavení vlastností služby Blob Service
Vytvoření, výpis nebo odstranění kontejnerů
Vytvoření, čtení, seznam, aktualizace, odstranění objektů blob bloku
Vytvoření, čtení, seznam, aktualizace nebo odstranění objektů blob stránky
Vytvoření, čtení, seznam, aktualizace nebo odstranění doplňovacího objektu blob

Klíčové odkazy

zdrojového kódu
balíčku (npm)
Referenční dokumentace k rozhraní API
dokumentace k produktu
ukázky
rozhraní REST API objektů blob služby Azure Storage

Začínáme

Aktuálně podporovaná prostředí

LTS verze Node.js
Nejnovější verze Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

Předplatné Azure
účtu úložiště

Instalace balíčku

Upřednostňovaným způsobem instalace klientské knihovny objektů blob služby Azure Storage pro JavaScript je použití správce balíčků npm. Do okna terminálu zadejte následující:

npm install @azure/storage-blob

Ověření klienta

Azure Storage podporuje několik způsobů ověřování. Pokud chcete pracovat se službou Azure Blob Storage, budete muset vytvořit instanci klienta služby Storage – BlobServiceClient, ContainerClientnebo BlobClient. Další informace o ověřování najdete v ukázkách pro vytvoření BlobServiceClient.

Azure Active Directory
sdílený klíč
sdílených přístupových podpisů

Azure Active Directory

Služba Azure Blob Storage podporuje použití Azure Active Directory k ověřování požadavků na jeho rozhraní API. Balíček @azure/identity poskytuje řadu typů přihlašovacích údajů, které může vaše aplikace použít k tomu. Další podrobnosti a ukázky, které vám pomůžou začít, najdete v souboru README pro @azure/identity.

Kompatibilita

Tato knihovna je kompatibilní s Node.js a prohlížeči a ověřuje se ve verzích LTS Node.js (>=8.16.0) a nejnovějších verzích Chromu, Firefoxu a Edge.

Webové pracovní procesy

Tato knihovna vyžaduje, aby byly určité objekty MODELU DOM globálně dostupné při použití v prohlížeči, které webové pracovní procesy ve výchozím nastavení nedostupují. Pokud chcete, aby tato knihovna fungovala ve webových pracovních pracovních procesůch, budete je muset polyfillovat.

Další informace najdete v naší dokumentaci k používání sady Azure SDK pro JS ve webových pracovních

Tato knihovna závisí na následujících rozhraních API DOM, která potřebují externí polyfilly načtené při použití ve webových pracovních procesů:

Rozdíly mezi Node.js a prohlížeči

Mezi modulem runtime Node.js a prohlížečů existují rozdíly. Při zahájení práce s touto knihovnou věnujte pozornost rozhraním API nebo třídám označeným "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "POUZE DOSTUPNÉ V PROHLÍŽEČÍCH".

Pokud objekt blob obsahuje komprimovaná data ve formátu gzip nebo deflate a jeho kódování obsahu se odpovídajícím způsobem nastaví, chování při stahování se liší mezi Node.js a prohlížeči. V Node.js klienti úložiště stáhnou objekt blob v komprimovaném formátu, zatímco v prohlížečích se data stáhnou v dekomprimovaném formátu.

Funkce, rozhraní, třídy nebo funkce dostupné pouze v Node.js

Autorizace sdíleného klíče na základě názvu účtu a klíče účtu
- StorageSharedKeyCredential
Generování sdíleného přístupového podpisu (SAS)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Paralelní nahrávání a stahování Všimněte si, že BlockBlobClient.uploadData() je k dispozici v Node.js i prohlížečích.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Funkce, rozhraní, třídy nebo funkce dostupné pouze v prohlížečích

Paralelní nahrávání a stahování
- BlockBlobClient.uploadBrowserData()

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci sdružování.

CORS

Pokud potřebujete vyvíjet prohlížeče, musíte pro svůj účet úložiště nastavit sdílení prostředků mezi zdroji (CORS) pravidla. Přejděte na Azure Portal a Průzkumníka služby Azure Storage, vyhledejte svůj účet úložiště, vytvořte nová pravidla CORS pro služby blob, queue, file/table service.

Můžete například vytvořit následující nastavení CORS pro ladění. Přizpůsobte si ale nastavení pečlivě podle svých požadavků v produkčním prostředí.

Povolené původy: *
Povolené příkazy: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
Povolené hlavičky: *
Vystavené hlavičky: *
Maximální stáří (sekundy): 86400

Klíčové koncepty

Úložiště objektů blob je navržené pro:

Poskytování obrázků nebo dokumentů přímo do prohlížeče
Ukládání souborů pro distribuovaný přístup
Streamování videa a zvuku
Zápis do souborů protokolu
Ukládání dat pro zálohování a obnovení, zotavení po havárii a archivaci
Ukládání dat pro analýzu místní službou nebo službou hostované v Azure

Blob Storage nabízí tři typy prostředků:

Účet úložiště použitý prostřednictvím BlobServiceClient
Kontejner v účtu úložiště použitém prostřednictvím ContainerClient
objekt blob v kontejneru použitém prostřednictvím BlobClient

Příklady

Import balíčku
vytvoření klienta služby Blob Service
Vytvoření nového kontejneru
Vypsat kontejnery
vytvoření objektu blob nahráním dat
Výpis objektů blob uvnitř kontejneru
Stažení objektu blob a jeho převod na řetězec (Node.js)
Stažení objektu blob a jeho převod na řetězec (prohlížeče)

Import balíčku

Pokud chcete použít klienty, naimportujte balíček do souboru:

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

Alternativně selektivně importujte jenom ty typy, které potřebujete:

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

Vytvoření klienta služby Blob Service

BlobServiceClient vyžaduje adresu URL služby blob a přihlašovací údaje pro přístup. Volitelně také přijímá některá nastavení v parametru options.

s `DefaultAzureCredential` z balíčku `@azure/identity`

Doporučený způsob vytvoření instance BlobServiceClient

Nastavení: Referenční informace – Autorizace přístupu k objektům blob a frontám pomocí Azure Active Directory z klientské aplikace – /azure/storage/common/storage-auth-aad-app

Registrace nové aplikace AAD a udělení oprávnění pro přístup ke službě Azure Storage jménem přihlášeného uživatele
- Registrace nové aplikace v Azure Active Directory (na webu azure-portal) – /azure/active-directory/develop/quickstart-register-app
- V části API permissions vyberte Add a permission a zvolte Microsoft APIs.
- Vyberte Azure Storage a zaškrtněte políčko vedle user_impersonation a potom klikněte na Add permissions. To by aplikaci umožnilo přístup ke službě Azure Storage jménem přihlášeného uživatele.
Udělení přístupu k datům objektů blob Azure pomocí RBAC na webu Azure Portal
- Role RBAC pro objekty blob a fronty – /azure/storage/common/storage-auth-aad-rbac-portal.
- Na webu Azure Portal přejděte do svého účtu úložiště a přiřaďte Roli Přispěvatel dat objektů blob služby Storage zaregistrované aplikaci AAD na kartě Access control (IAM) (na levém navigačním panelu účtu úložiště na webu Azure-Portal).
Nastavení prostředí pro ukázku
- Na stránce přehledu aplikace AAD si poznamenejte CLIENT ID a TENANT ID. Na kartě Certifikáty & Tajné kódy vytvořte tajný kód a poznamenejte si ho.
- Ujistěte se, že máte AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET jako proměnné prostředí k úspěšnému spuštění ukázky (může využít 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
);

Úplnou ukázku použití této metody najdete v ukázkové ověřování Azure AD.

[Poznámka: Výše uvedené kroky jsou určené pouze pro Node.js]

pomocí připojovacího řetězce

Alternativně můžete vytvořit instanci BlobServiceClient pomocí fromConnectionString() statické metody s úplným připojovacím řetězcem jako argumentem. (Připojovací řetězec lze získat z webu Azure Portal.) [K DISPOZICI POUZE V NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

s `StorageSharedKeyCredential`

Alternativně vytvoříte instanci BlobServiceClient s StorageSharedKeyCredential předáním názvu účtu a klíče účtu jako argumentů. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V 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
);

s tokenem SAS

Můžete také vytvořit instanci BlobServiceClient se sdílenými přístupovými podpisy (SAS). Token SAS můžete získat z webu Azure Portal nebo ho vygenerovat pomocí 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}`);

Vytvoření nového kontejneru

Pomocí BlobServiceClient.getContainerClient() získejte instanci klienta kontejneru a pak vytvořte nový prostředek kontejneru.

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

Výpis kontejnerů

Pomocí funkce BlobServiceClient.listContainers() iterujte kontejnery s novou syntaxí 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 containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

Alternativně bez použití 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();

Kromě toho se stránkování podporuje také pro výpis prostřednictvím 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();

Kompletní ukázku iterace kontejnerů najdete v tématu samples/v12/typescript/src/listContainers.ts.

Vytvoření objektu blob nahráním dat

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

Výpis objektů blob uvnitř kontejneru

Podobá se výpisu kontejnerů.

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

Kompletní ukázku iterace objektů blob najdete v tématu samples/v12/typescript/src/listBlobsFlat.ts.

Stáhněte objekt blob a převeďte ho na řetězec (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();

Stáhněte objekt blob a převeďte ho na řetězec (prohlížeče).

Další informace o používání této knihovny v prohlížeči najdete v části 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();

Úplný příklad jednoduchých scénářů je v samples/v12/typescript/src/sharedKeyAuth.ts.

Řešení problémů

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Další kroky

Další ukázky kódu:

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

Další informace o nastavení testovacího prostředí pro knihovny úložiště najdete také v průvodci Storage.

imprese

Sdílet prostřednictvím

Klientská knihovna Azure Storage Blob pro JavaScript – verze 12.24.0

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Ověření klienta

Azure Active Directory

Kompatibilita

Webové pracovní procesy

Rozdíly mezi Node.js a prohlížeči

Funkce, rozhraní, třídy nebo funkce dostupné pouze v Node.js

Funkce, rozhraní, třídy nebo funkce dostupné pouze v prohlížečích

JavaScript Bundle

CORS

Klíčové koncepty

Příklady

Import balíčku

Vytvoření klienta služby Blob Service

s `DefaultAzureCredential` z balíčku `@azure/identity`

pomocí připojovacího řetězce

s `StorageSharedKeyCredential`

s tokenem SAS

Vytvoření nového kontejneru

Výpis kontejnerů

Vytvoření objektu blob nahráním dat

Výpis objektů blob uvnitř kontejneru

Stáhněte objekt blob a převeďte ho na řetězec (Node.js)

Stáhněte objekt blob a převeďte ho na řetězec (prohlížeče).

Řešení problémů

Další kroky

Přispívající

Další materiály

Sdílet prostřednictvím

Klientská knihovna Azure Storage Blob pro JavaScript – verze 12.24.0

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Ověření klienta

Azure Active Directory

Kompatibilita

Webové pracovní procesy

Rozdíly mezi Node.js a prohlížeči

Funkce, rozhraní, třídy nebo funkce dostupné pouze v Node.js

Funkce, rozhraní, třídy nebo funkce dostupné pouze v prohlížečích

JavaScript Bundle

CORS

Klíčové koncepty

Příklady

Import balíčku

Vytvoření klienta služby Blob Service

s DefaultAzureCredential z balíčku @azure/identity

pomocí připojovacího řetězce

s StorageSharedKeyCredential

s tokenem SAS

Vytvoření nového kontejneru

Výpis kontejnerů

Vytvoření objektu blob nahráním dat

Výpis objektů blob uvnitř kontejneru

Stáhněte objekt blob a převeďte ho na řetězec (Node.js)

Stáhněte objekt blob a převeďte ho na řetězec (prohlížeče).

Řešení problémů

Další kroky

Přispívající

Další materiály

s `DefaultAzureCredential` z balíčku `@azure/identity`

s `StorageSharedKeyCredential`