Azure Storage File Data Lake JavaScript-ügyféloldali kódtár – 12.28.1-es verzió

Az Azure Data Lake Storage (ADLS) tartalmazza azokat a képességeket, amelyek szükségesek ahhoz, hogy a fejlesztők, az adattudósok és az elemzők egyszerűen tárolhassanak bármilyen méretű, formájú és sebességű adatokat, és minden típusú feldolgozást és elemzést végezzenek különböző platformokon és nyelveken. Eltávolítja az összes adat betöltésének és tárolásának összetettségét, miközben gyorsabbá teszi a kötegelt, streamelt és interaktív elemzések használatát.

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

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

• Fájlrendszerek létrehozása/listázása/törlése
• Elérési utak, könyvtárak és fájlok létrehozása/olvasása/listázása/frissítése/törlése

Főbb linkek:

• forráskód
• Csomag (npm)
• API referenciadokumentációja
• termékdokumentáció
• Samples
• Azure Storage Data Lake REST API-k

Kezdő lépések

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 .

Prerequisites

• Azure-előfizetés
• Tárfiók

A csomag telepítése

A JavaScripthez készült Azure Storage Data Lake-ü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-file-datalake

Az ügyfél hitelesítése

Az Azure Storage számos módon támogatja a hitelesítést. Az Azure Data Lake Storage szolgáltatás használatához létre kell hoznia egy Storage-ügyfélpéldányt – például DataLakeServiceClient, DataLakeFileSystemClientvagy DataLakePathClient. 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 Data Lake Storage szolgáltatás támogatja az Azure Active Directory használatát az API-khoz érkező kérések 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.

Compatibility

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.

Webes dolgozók

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:

• document
• DOMParser
• Node
• XMLSerializer

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 fájl gzip vagy deflate formátumban tárolja a tömörített adatokat, és a tartalomkódolás ennek megfelelően van beállítva, a letöltési viselkedés eltér a Node.js és a böngészők között. A Node.js storage-ügyfelek tömörített formátumban töltik le a fájlt, 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()
  • generateDataLakeSASQueryParameters()
• Párhuzamos feltöltés és letöltés. Vegye figyelembe, hogy DataLakeFileClient.upload() Node.js és böngészőkben is elérhető.
  • DataLakeFileClient.uploadFile()
  • DataLakeFileClient.uploadStream()
  • DataLakeFileClient.readToBuffer()
  • DataLakeFileClient.readToFile()

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

• N/A

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 a kötegelési dokumentációban olvashat.

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

Megjegyzés: A Data Lake jelenleg a blobszolgáltatás CORS-beállításait osztja meg.

Főbb fogalmak

Az Azure Data Lake Storage Gen2 a következőre lett tervezve:

• Több petabájtnyi információ kiszolgálása több száz gigabájtos átviteli sebesség fenntartása mellett
• Lehetővé teszi nagy mennyiségű adat egyszerű kezelését

A DataLake Storage Gen2 főbb funkciói a következők:

• Hadoop-kompatibilis hozzáférés
• POSIX-engedélyek szuperkészlete
• Költséghatékony az alacsony költségű tárolási kapacitás és a tranzakciók szempontjából
• Optimalizált illesztőprogram big data-elemzéshez

A Data Lake Storage Gen2 alapvető része egy hierarchikus névtér hozzáadása a Blob Storage-hoz. A hierarchikus névtér az objektumokat/fájlokat címtárak hierarchiájába rendezi a hatékony adathozzáférés érdekében.

A múltban a felhőalapú elemzésnek kompromisszumot kellett kötnie a teljesítmény, a felügyelet és a biztonság területén. A Data Lake Storage Gen2 az alábbi szempontok mindegyikével foglalkozik:

• A teljesítmény optimalizálva van, mert nem kell adatokat másolnia vagy átalakítania az elemzés előfeltételeként. A hierarchikus névtér jelentősen javítja a címtárkezelési műveletek teljesítményét, ami javítja a feladatok általános teljesítményét.
• A felügyelet egyszerűbb, mert könyvtárakon és alkönyvtárakon keresztül rendszerezheti és kezelheti a fájlokat.
• A biztonság kikényszeríthető, mert POSIX-engedélyeket határozhat meg könyvtárakra vagy egyedi fájlokra.
• A költséghatékonyság azért lehetséges, mert a Data Lake Storage Gen2 az alacsony költségű Azure Blob Storage-ra épül. A további funkciók tovább csökkentik a big data-elemzések Azure-beli futtatásának teljes bekerülési költségét.

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

• A használatával használt tárfiókDataLakeServiceClient
• A tárfiók fájlrendszere, amelyet a DataLakeFileSystemClient
• Elérési út egy fájlrendszerben a vagy DataLakeDirectoryClientDataLakeFileClient

Azure DataLake Gen2	Blob
Filesystem	Container
Elérési út (fájl vagy könyvtár)	Blob

Megjegyzés: Ez az ügyfélkódtár csak a hierarchikus névtérrel (HNS) rendelkező tárfiókokat támogatja.

Examples

• Csomag importálása
• Data Lake Service-ügyfélalkalmazás létrehozása
• Új fájlrendszer létrehozása
• A fájlrendszerek listázása
• Címtár létrehozása és törlése
• Fájl létrehozása
• Fájlrendszeren belüli elérési utak listázása
• Fájl letöltése és sztringgé alakítása (Node.js)
• Fájl letöltése és konvertálása sztringgé (Böngészők)

A csomag importálása

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

import * as AzureStorageDataLake from "@azure/storage-file-datalake";

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

import { DataLakeServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-datalake";

A Data Lake Service-ügyfél létrehozása

A DataLakeServiceClient a data lake szolgáltatás URL-címét és egy hozzáférési hitelesítő adatot igényel. Emellett a options paraméter bizonyos beállításait is elfogadja.

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

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

Notice. Az Azure Data Lake jelenleg újra felhasználja a blobokkal kapcsolatos szerepköröket, például a "Storage Blob Data Owner" szerepkört az AAD OAuth-hitelesítés során.

Beállítás: Referencia – Blobokhoz (Data Lake) é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

• Regisztráljon egy új AAD-alkalmazást, és adjon engedélyeket 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.

• Hozzáférés biztosítása az Azure Data Lake-adatokhoz az RBAC-vel az Azure Portalon

  • RBAC-szerepkörök blobokhoz (Data Lake) é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 { DataLakeServiceClient } from "@azure/storage-file-datalake";

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.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 DataLakeServiceClient 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 { DataLakeServiceClient } from "@azure/storage-file-datalake";

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

StorageSharedKeyCredential

Másik lehetőségként a fióknév és a fiókkulcs argumentumként való átadásával egy DataLakeServiceClientStorageSharedKeyCredential 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, DataLakeServiceClient } from "@azure/storage-file-datalake";

// 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 datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential,
);

SAS-jogkivonattal

Emellett egy DataLakeServiceClient 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 { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

Új fájlrendszer létrehozása

A DataLakeServiceClient.getFileSystemClient() használatával szerezze be a fájlrendszer ügyfélpéldányát, majd hozzon létre egy új fájlrendszer-erőforrást.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a file system
const fileSystemName = `newfilesystem${new Date().getTime()}`;
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const createResponse = await fileSystemClient.create();
console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);

A fájlrendszerek listázása

A fájlrendszerek iterálásához használja DataLakeServiceClient.listFileSystems() függvényt az új for-await-of szintaxissal:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
for await (const fileSystem of fileSystems) {
  console.log(`File system ${i++}: ${fileSystem.name}`);
}

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

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
let { value, done } = await fileSystems.next();
while (!done) {
  console.log(`File system ${i++}: ${value.name}`);
  ({ value, done } = await fileSystems.next());
}

Emellett a lapozás is támogatott a listázáshoz a byPage():

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const response of datalakeServiceClient.listFileSystems().byPage({ maxPageSize: 20 })) {
  if (response.fileSystemItems) {
    for (const fileSystem of response.fileSystemItems) {
      console.log(`File System ${i++}: ${fileSystem.name}`);
    }
  }
}

Címtár létrehozása és törlése

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const directoryClient = fileSystemClient.getDirectoryClient("directory");
await directoryClient.create();
await directoryClient.delete();

Fájl létrehozása

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

const content = "Hello world!";
const fileName = `newfile${+new Date()}`;
const fileClient = fileSystemClient.getFileClient(fileName);
await fileClient.create();
await fileClient.append(content, 0, content.length);
await fileClient.flush(content.length);
console.log(`Create and upload file ${fileName} successfully`);

Elérési utak listázása fájlrendszeren belül

Hasonló a fájlrendszerek felsorolásához.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

let i = 1;
const paths = fileSystemClient.listPaths();
for await (const path of paths) {
  console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
}

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

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadResponse.readableStreamBody
const downloadResponse = await fileClient.read();
if (downloadResponse.readableStreamBody) {
  const downloaded = await streamToBuffer(downloadResponse.readableStreamBody);
  console.log("Downloaded file content:", downloaded.toString());
}

// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer.
async function streamToBuffer(readableStream: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

Fájl letöltése és sztringgé alakítása (Böngészők)

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account>";
const sas = "<sas token>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
const downloadResponse = await fileClient.read();
if (downloadResponse.contentAsBlob) {
  const blob = await downloadResponse.contentAsBlob;
  const downloaded = await blob.text();
  console.log(`Downloaded file content ${downloaded}`);
}

Troubleshooting

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:

• DataLake Storage-minták (JavaScript)
• DataLake Storage-minták (TypeScript)
• DataLake Storage-tesztesetek

Contributing

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.