Azure Storage Blob ügyféloldali kódtár JavaScripthez – 12.29.1-es verzió

Az Azure Storage Blob a Microsoft objektumtárolási megoldása a felhőhöz. A Blob Storage nagy mennyiségű strukturálatlan adat tárolására van optimalizálva. A strukturálatlan adatok olyan adatok, amelyek nem igazodnak egy adott adatmodellhez vagy definícióhoz, például szöveges vagy bináris adatokhoz.

Ez a projekt egy JavaScript-ügyfélkódtárat biztosít, amely megkönnyíti a Microsoft Azure Storage Blob szolgáltatás használatát.

A csomagban található ügyfélkódtárak használatával:

Blobszolgáltatás tulajdonságainak lekérése/beállítása
Tárolók létrehozása/listázása/törlése
Blokkblobok létrehozása/olvasása/listázása/frissítése/törlése
Lapblobok létrehozása/olvasása/listázása/frissítése/törlése
Hozzáfűző blobok létrehozása/olvasása/listázása/frissítése/törlése

Kulcshivatkozások

Kezdetekhez

Jelenleg támogatott környezetek

A Node.js LTS-verziói
A Safari, a Chrome, az Edge és a Firefox legújabb verziói.

További részletekért tekintse meg támogatási szabályzatunkat.

Előfeltételek

Egy Azure-előfizetés
Egy Storage-fiók

A csomag telepítése

A JavaScripthez készült Azure Storage Blob-ügyfélkódtár telepítésének elsődleges módja az npm-csomagkezelő használata. Írja be a következőt egy terminálablakba:

npm install @azure/storage-blob

Az ügyfél hitelesítése

Az Azure Storage számos módon támogatja a hitelesítést. Az Azure Blob Storage szolgáltatás használatához létre kell hoznia egy Storage-ügyfélpéldányt – például BlobServiceClient, ContainerClientvagy BlobClient. A létrehozásához tekintse meg mintákat a hitelesítésről.

Azure Active Directory
megosztott kulcs
közös hozzáférésű jogosultságkódok

Azure Active Directory

Az Azure Blob Storage szolgáltatás támogatja az Azure Active Directory használatát az API-khoz érkező kérelmek hitelesítéséhez. A @azure/identity csomag számos hitelesítő adattípust biztosít, amelyeket az alkalmazás használhat erre. További részletekért és mintákért tekintse meg a README-et.

Kompatibilitás

Ez a kódtár kompatibilis a Node.js és a böngészőkkel, és az LTS Node.js (>=8.16.0) és a Chrome, a Firefox és az Edge legújabb verzióival van érvényesítve.

Webmunkások

Ehhez a kódtárhoz bizonyos DOM-objektumoknak globálisan elérhetővé kell lenniük a böngészőben való használatkor, amelyeket a webmunkások alapértelmezés szerint nem tesznek elérhetővé. Ezeket a függvénytárat a webmunkásokban való működéshez többszörösen kell feltöltenie.

További információkért tekintse meg dokumentációnkat az Azure SDK for JS webmunkásokban való használatához

Ez a kódtár a következő DOM API-któl függ, amelyek a webmunkásokban való használathoz külső polifilleket igényelnek:

Különbségek a Node.js és a böngészők között

A Node.js és a böngésző futtatókörnyezete között különbségek vannak. A kódtár használatbavételekor figyelje meg a "CSAK ELÉRHETŐ NODE.JS FUTTATÓKÖRNYEZETBEN" megjelölt API-kat vagy osztályokat, vagy "CSAK BÖNGÉSZŐBEN ELÉRHETŐ".

Ha egy blob tömörített adatokat tárol gzip vagy deflate formátumban, és a tartalomkódolás ennek megfelelően van beállítva, a letöltési viselkedés Node.js és böngészők között eltérő. A Node.js storage-ügyfelek tömörített formátumban töltik le a blobot, míg böngészőkben az adatok tömörített formátumban lesznek letöltve.

Szolgáltatások, felületek, osztályok vagy függvények csak Node.js

Megosztott kulcs engedélyezése a fióknév és a fiókkulcs alapján
- StorageSharedKeyCredential
Közös hozzáférésű jogosultságkód (SAS) létrehozása
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Párhuzamos feltöltés és letöltés. Vegye figyelembe, hogy BlockBlobClient.uploadData() Node.js és böngészőkben is elérhető.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Szolgáltatások, felületek, osztályok vagy függvények csak böngészőkben érhetők el

Párhuzamos feltöltés és letöltés
- BlockBlobClient.uploadBrowserData()

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, először egy kötegelőt kell használnia. Ennek módjáról további információt a csomagküldő dokumentációbantalál.

CORS

Ha böngészőkre van szüksége, be kell állítania forrásközi erőforrás-megosztási (CORS) szabályokat a tárfiókhoz. Nyissa meg az Azure Portalt és az Azure Storage Explorert, keresse meg a tárfiókot, hozzon létre új CORS-szabályokat a blob-/üzenetsor-/fájl-/táblaszolgáltatás(ok)hoz.

A hibakereséshez például az alábbi CORS-beállításokat hozhatja létre. Azonban az éles környezetben a követelményeknek megfelelően szabja testre a beállításokat.

Engedélyezett források: *
Engedélyezett parancsok: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Engedélyezett fejlécek: *
Közzétett fejlécek: *
Maximális életkor (másodperc): 86400

Főbb fogalmak

A Blob Storage a következő célokra lett kialakítva:

Képek vagy dokumentumok közvetlenül egy böngészőben való kiszolgálása.
Fájlok tárolása elosztott hozzáféréshez.
Video- és hangstreamelés.
Írás naplófájlba.
Adatok tárolása biztonsági mentéshez és visszaállításhoz, vészhelyreállításhoz és archiváláshoz.
Adatok tárolása helyszíni vagy Azure-ban üzemeltetett szolgáltatás által végzett elemzéshez.

A Blob Storage háromféle erőforrást kínál:

A keresztül használt BlobServiceClient
Egy tároló a ContainerClient keresztül használt tárfiókban
Egy blob egy BlobClient keresztül használt tárolóban

Példák

Csomag importálása
Blob Service-ügyfél létrehozása
Új tároló létrehozása
Tárolók listázása
Blob létrehozása adatok feltöltésével
Blobok listázása tárolóban
Blob letöltése és sztringgé alakítása (Node.js)
Blob letöltése és sztring (Böngészők)

A csomag importálása

Az ügyfelek használatához importálja a csomagot a fájlba:

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

Másik lehetőségként csak a szükséges típusokat importálja szelektíven:

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

A blobszolgáltatás-ügyfél létrehozása

A BlobServiceClient megköveteli a blobszolgáltatás URL-címét és a hozzáférési hitelesítő adatokat. Emellett a options paraméter bizonyos beállításait is elfogadja.

`DefaultAzureCredential` csomagból származó `@azure/identity`

Ajánlott módszer a BlobServiceClient példányosítására

Beállítás: Referencia – Blobokhoz és üzenetsorokhoz való hozzáférés engedélyezése Azure Active Directory ügyfélalkalmazásból – https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

Új AAD-alkalmazás regisztrálása és engedélyek megadása az Azure Storage eléréséhez a bejelentkezett felhasználó nevében
- Új alkalmazás regisztrálása a Azure Active Directory (az azure-portalon) – https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- A API permissions szakaszban válassza a Add a permission, majd a Microsoft APIslehetőséget.
- Jelölje be a Azure Storage, és jelölje be a user_impersonation melletti jelölőnégyzetet, majd kattintson a Add permissionsgombra. Ez lehetővé tenné az alkalmazás számára, hogy a bejelentkezett felhasználó nevében hozzáférjen az Azure Storage-hoz.
Azure Blob-adatokhoz való hozzáférés biztosítása RBAC-vel az Azure Portalon
- RBAC-szerepkörök blobokhoz és üzenetsorokhoz – . https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal
- Az Azure Portalon nyissa meg a tárfiókot, és rendeljen hozzá Storage Blob-adatszolgáltatói szerepkört a regisztrált AAD-alkalmazáshoz Access control (IAM) lapról (a tárfiók bal oldali navigációs sávján az azure-portalon).
A minta környezetbeállítása
- Az AAD-alkalmazás áttekintési oldalán jegyezze fel a CLIENT ID és a TENANT ID. A "Tanúsítványok & titkos kulcsok" lapon hozzon létre egy titkos kulcsot, és jegyezze fel ezt lefelé.
- Győződjön meg arról, hogy AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET környezeti változókkal rendelkezik a minta sikeres végrehajtásához (használhatja a process.env parancsot).

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

A metódust használó teljes példáért tekintse meg az Azure AD-hitelesítési minta.

[Megjegyzés – A fenti lépések csak Node.js]

kapcsolati sztring használata

Másik lehetőségként létrehozhat egy BlobServiceClient a fromConnectionString() statikus metódussal, argumentumként pedig a teljes kapcsolati sztringgel. (A kapcsolati sztring az Azure Portalról kérhető le.) [CSAK NODE.JS FUTTATÓKÖRNYEZETBEN ÉRHETŐ EL]

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

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

`StorageSharedKeyCredential`

Másik lehetőségként a fióknév és a fiókkulcs argumentumként való átadásával egy BlobServiceClientStorageSharedKeyCredential példányosíthat. (A fióknév és a fiókkulcs az Azure Portalon szerezhető be.) [CSAK NODE.JS FUTTATÓKÖRNYEZETBEN ÉRHETŐ EL]

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

SAS-jogkivonattal

Emellett egy BlobServiceClient is létrehozhat közös hozzáférésű jogosultságkódokkal (SAS). Az SAS-jogkivonatot lekérheti az Azure Portalról, vagy létrehozhat egyet generateAccountSASQueryParameters()használatával.

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}`);

Új tároló létrehozása

A BlobServiceClient.getContainerClient() használatával szerezze be a tárolóügyfél-példányt, majd hozzon létre egy új tárolóerőforrást.

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

A tárolók listázása

A tárolók iterálásához használja BlobServiceClient.listContainers() függvényt az új for-await-of szintaxissal:

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}`);
}

Másik lehetőségként for-await-ofhasználata nélkül:

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

Emellett a lapozás is támogatott a listázáshoz a 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}`);
  }
}

Az iterálási tárolók teljes mintájáért tekintse meg mintákat/v12/typescript/src/listContainers.ts.

Blob létrehozása adatok feltöltésével

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}`,
);

Blobok listázása tárolón belül

Hasonló a tárolók listázásához.

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}`);
}

Az iterálási blobokra vonatkozó teljes mintát minták/v12/typescript/src/listBlobsFlat.tscímű témakörben talál.

Blob letöltése és sztringgé alakítása (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();
}

Töltsön le egy blobot, és konvertálja sztringgé (Browsers).

A kódtár böngészőben való használatáról további információt a JavaScript-csomag szakaszában talál.

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}`);
}

Az egyszerű forgatókönyvek teljes példája minták/v12/typescript/src/sharedKeyAuth.ts.

Hibaelhárítás

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a AZURE_LOG_LEVEL környezeti változót info. Másik lehetőségként a naplózás futásidőben is engedélyezhető a setLogLevel meghívásával a @azure/logger:

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

setLogLevel("info");

Következő lépések

További kódminták:

Hozzájárulás

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót, amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

A tárolótárak tesztkörnyezetének beállításával kapcsolatos további információkért tekintse meg társpecifikus útmutatót.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-10-17