Klientská knihovna Azure Storage Blob pro JavaScript – verze 12.23.0

Článek
06/06/2024

Azure Storage Blob je řešení úložiště objektů pro cloud od Microsoftu. Služba Blob Storage je optimalizovaná pro ukládání velkých objemů nestrukturovaných dat. Jde o data, která nevyhovují konkrétnímu datovému modelu nebo definici, například 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.

Pomocí klientských knihoven v tomto balíčku:

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

Klíčové odkazy

Začínáme

Aktuálně podporovaná prostředí

LtS verze Node.js
Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

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

Požadavky

Instalace balíčku

Upřednostňovaným způsobem instalace klientské knihovny Azure Storage Blob 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í. Abyste mohli pracovat se službou Azure Blob Storage, musíte vytvořit instanci klienta služby Storage , BlobServiceClientContainerClientnebo BlobClient například . Další informace o ověřování najdete v BlobServiceClientukázkách pro vytvoření.

Azure Active Directory
Sdílený klíč
Sdílené přístupové podpisy

Azure Active Directory

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

Kompatibilita

Tato knihovna je kompatibilní s Node.js a prohlížeči a je ověřená ve verzích LTS Node.js (>=8.16.0) a nejnovějších verzích prohlížečů Chrome, Firefox a Edge.

Webové pracovní procesy

Tato knihovna vyžaduje, aby určité objekty MODELU DOM byly při použití v prohlížeči globálně dostupné, což webové pracovní procesy ve výchozím nastavení nezpřístupní. Aby tato knihovna fungovala ve webových pracovnící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 procesůch.

Tato knihovna závisí na následujících rozhraních API dom, která při použití ve webových pracovních procesů vyžadují načtení externích polyfillů:

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

Mezi modulem runtime Node.js a prohlížeče existují rozdíly. Když začínáte s touto knihovnou, věnujte pozornost rozhraním API nebo třídám označeným "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "K DISPOZICI POUZE V PROHLÍŽEČÍCH".

Pokud objekt blob obsahuje komprimovaná data ve gzip formátu nebo deflate a jeho kódování obsahu je nastaveno odpovídajícím způsobem, chování stahování se mezi Node.js a prohlížeči liší. V Node.js storage klienti 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í. Mějte na paměti, že BlockBlobClient.uploadData() je k dispozici v Node.js i v 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žívat v prohlížeči, musíte nejprve použít nástroj bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

CORS

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

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í věk (sekundy): 86400

Klíčové koncepty

Úložiště objektů blob je navržena 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ů protokolů
Ukládání dat pro zálohování a obnovování, zotavení po havárii a pro archivaci
Ukládání dat, která bude analyzovat místní nebo v Azure hostovaná služba

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

Účet úložiště použitý prostřednictvímBlobServiceClient
Kontejner v účtu úložiště, který se používá prostřednictvímContainerClient
Objekt blob v kontejneru, který se používá prostřednictvímBlobClient

Příklady

Import balíčku
Vytvoření klienta služby Blob Service
Vytvoření nového kontejneru
Výpis kontejnerů
Vytvoření objektu blob nahráním dat
Výpis objektů blob uvnitř kontejneru
Stažení objektu blob a jeho převedení 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, importujte balíček do souboru:

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

Případně můžete selektivně importovat pouze typy, které potřebujete:

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

Vytvoření klienta služby Blob Service

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

s balíčkem `DefaultAzureCredential` z `@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 oddílu API permissions vyberte Add a permission a zvolte Microsoft APIs.
- Zaškrtněte Azure Storage a zaškrtněte políčko vedle user_impersonation a 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 na svůj účet úložiště a na kartě (v levém navigačním panelu účtu úložiště na webu azure-portal) přiřaďte zaregistrované aplikaci Access control (IAM) AAD roli Přispěvatel dat v objektech blob služby Storage.
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 pro úspěšné spuštění ukázky máte AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET jako proměnné prostředí(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
);

Úplný příklad použití této metody najdete v ukázce ověřování Azure AD .

[Poznámka – Výše uvedené kroky jsou určené jenom pro Node.js.

pomocí připojovacího řetězce

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

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

S `StorageSharedKeyCredential`

Případně můžete vytvořit instanci BlobServiceClient s argumentem StorageSharedKeyCredential account-name a account-key. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V modulu runtime NODE.JS]

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 BlobServiceClient instanci 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

Použijte BlobServiceClient.getContainerClient() k získání instance klienta kontejneru a následnému vytvoření nového prostředku 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ů

K iteraci kontejnerů použijte BlobServiceClient.listContainers() funkci s novou for-await-of syntaxí:

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

Případně 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 je stránkování podporováno 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.

Stažení objektu blob a jeho převedení 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 si 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ým příkladem jednoduchých scénářů je samples/v12/typescript/src/sharedKeyAuth.ts.

Poradce při potížích

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné 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ívání

Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.

Další informace o nastavení testovacího prostředí pro knihovny úložiště najdete také v příručce pro konkrétní úložiště.

Imprese

Sdílet prostřednictvím

Klientská knihovna Azure Storage Blob pro JavaScript – verze 12.23.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 balíčkem `DefaultAzureCredential` z `@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

Stažení objektu blob a jeho převedení na řetězec (Node.js)

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

Poradce při potížích

Další kroky

Přispívání

Váš názor

Další materiály

Sdílet prostřednictvím

Klientská knihovna Azure Storage Blob pro JavaScript – verze 12.23.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 balíčkem DefaultAzureCredential z @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

Stažení objektu blob a jeho převedení na řetězec (Node.js)

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

Poradce při potížích

Další kroky

Přispívání

Váš názor

Další materiály

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

S `StorageSharedKeyCredential`