Klientská knihovna Azure Storage Blob pro JavaScript – verze 12.29.1

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í/vypsání/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ý kód
Balíček (npm)
Referenční dokumentace k rozhraní API
dokumentace k produktu
Samples
rozhraní REST API objektů blob služby Azure Storage

Začínáme

Aktuálně podporovaná prostředí

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

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

Prerequisites

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.

Compatibility

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íci

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

JavaScriptový balíček

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 k 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ímBlobServiceClient
Kontejner v účtu úložiště používaný prostřednictvímContainerClient
Objekt blob v kontejneru používaném prostřednictvímBlobClient

Examples

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:

import * as AzureStorageBlob from "@azure/storage-blob";

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

import { BlobServiceClient, StorageSharedKeyCredential } from "@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 – https://learn.microsoft.com/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 (v azure-portal) - https://learn.microsoft.com/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 - https://learn.microsoft.com/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).

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@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]

import { BlobServiceClient } from "@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]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

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

import { BlobServiceClient } from "@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.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Výpis kontejnerů

Pomocí funkce BlobServiceClient.listContainers() iterujte kontejnery s novou syntaxí for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Alternativně bez použití for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Kromě toho se stránkování podporuje také pro výpis prostřednictvím byPage():

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

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

Kompletní ukázku iteračních kontejnerů naleznete v tématu samples/v12/typescript/src/listContainers.ts.

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

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

Výpis objektů blob uvnitř kontejneru

Podobá se výpisu kontejnerů.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

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

Úplnou 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)

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
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();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

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 naleznete v části JavaScript Bundle .

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

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

const containerName = "<container name>";
const blobName = "<blob name>";
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 blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

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

Troubleshooting

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:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Další kroky

Další ukázky kódu:

Contributing

Pokud chcete přispívat do této knihovny, přečtěte si průvodce pro přispívání a přečtěte si další informace o tom, jak sestavit a otestovat kód.

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-17