Azure Storage Blob-ügyfélkódtár JavaScripthez – 12.24.0-s verzió

Cikk
07/24/2024

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

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 a támogatási szabályzat.

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 BlobServiceClient keresztül használt tárfiók
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:

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

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@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.

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

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

Telepítés: Referencia – Blobok és üzenetsorok hozzáférésének engedélyezése az Azure Active Directoryval egy ügyfélalkalmazásból – /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 az Azure Active Directoryban (az azure-portalon) – /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 – /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).

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

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]

const { BlobServiceClient } = require("@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 StorageSharedKeyCredentialBlobServiceClient 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]

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

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.

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

Ú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.

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

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:

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

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

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

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

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

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

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

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

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

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)

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

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.

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

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:

const { setLogLevel } = require("@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.

benyomások

Megosztás a következőn keresztül:

Azure Storage Blob-ügyfélkódtár JavaScripthez – 12.24.0-s verzió

Kezdetekhez

Jelenleg támogatott környezetek

Előfeltételek

A csomag telepítése

Az ügyfél hitelesítése

Azure Active Directory

Kompatibilitás

Webmunkások

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

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

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

JavaScript-csomag

CORS

Főbb fogalmak

Példák

A csomag importálása

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

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

kapcsolati sztring használata

`StorageSharedKeyCredential`

SAS-jogkivonattal

Új tároló létrehozása

A tárolók listázása

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

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

Blob letöltése és sztringgé alakítása (Node.js)

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

Hibaelhárítás

Következő lépések

Hozzájárulás

Visszajelzés

További források

Megosztás a következőn keresztül:

Azure Storage Blob-ügyfélkódtár JavaScripthez – 12.24.0-s verzió

Kezdetekhez

Jelenleg támogatott környezetek

Előfeltételek

A csomag telepítése

Az ügyfél hitelesítése

Azure Active Directory

Kompatibilitás

Webmunkások

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

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

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

JavaScript-csomag

CORS

Főbb fogalmak

Példák

A csomag importálása

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

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

kapcsolati sztring használata

StorageSharedKeyCredential

SAS-jogkivonattal

Új tároló létrehozása

A tárolók listázása

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

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

Blob letöltése és sztringgé alakítása (Node.js)

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

Hibaelhárítás

Következő lépések

Hozzájárulás

Visszajelzés

További források

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

`StorageSharedKeyCredential`