Azure Storage File Data Lake-klientbibliotek för JavaScript – version 12.25.0

Artikel
11/20/2024

Azure Data Lake Storage (ADLS) innehåller alla funktioner som krävs för att göra det enkelt för utvecklare, dataforskare och analytiker att lagra data av valfri storlek, form och hastighet och utföra alla typer av bearbetning och analys på plattformar och språk. Det tar bort komplexiteten i att mata in och lagra alla dina data samtidigt som det går snabbare att komma igång med batch-, strömnings- och interaktiv analys.

Det här projektet tillhandahåller ett klientbibliotek i JavaScript som gör det enkelt att använda Microsoft Azure Storage Data Lake-tjänsten.

Använd klientbiblioteken i det här paketet för att:

Skapa/lista/ta bort filsystem
Skapa/läsa/lista/uppdatera/ta bort sökvägar, kataloger och filer

nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportprincip.

Förutsättningar

En Azure-prenumeration
Ett lagringskonto

Installera paketet

Det bästa sättet att installera Azure Storage Data Lake-klientbiblioteket för JavaScript är att använda npm-pakethanteraren. Skriv följande i ett terminalfönster:

npm install @azure/storage-file-datalake

Autentisera klienten

Azure Storage stöder flera sätt att autentisera. För att kunna interagera med Azure Data Lake Storage-tjänsten måste du skapa en instans av en Storage-klient – DataLakeServiceClient, DataLakeFileSystemClienteller DataLakePathClient till exempel. Mer information om autentisering finns i exempel för att skapa DataLakeServiceClient.

Azure Active Directory
delad nyckel
Signaturer för delad åtkomst

Azure Active Directory

Azure Data Lake Storage-tjänsten stöder användning av Azure Active Directory för att autentisera begäranden till dess API:er. @azure/identity-paketet innehåller en mängd olika typer av autentiseringsuppgifter som programmet kan använda för att göra detta. Mer information och exempel finns i README för @azure/identity för att komma igång.

Kompatibilitet

Det här biblioteket är kompatibelt med Node.js och webbläsare och verifieras mot LTS-Node.js versioner (>=8.16.0) och de senaste versionerna av Chrome, Firefox och Edge.

Webbarbetare

Det här biblioteket kräver att vissa DOM-objekt är globalt tillgängliga när de används i webbläsaren, vilket webbarbetare inte gör tillgängliga som standard. Du måste polyfylla dessa för att det här biblioteket ska fungera i webbarbetare.

Mer information finns i vår dokumentation för att använda Azure SDK för JS i Web Workers

Det här biblioteket är beroende av följande DOM-API:er som behöver externa polyfyller som läses in när de används i webbarbetare:

Skillnader mellan Node.js och webbläsare

Det finns skillnader mellan Node.js och webbläsarkörning. När du kommer igång med det här biblioteket bör du vara uppmärksam på API:er eller klasser som har markerats med "ONLY AVAILABLE IN NODE.JS RUNTIME" eller "ONLY AVAILABLE IN BROWSERS".

Om en fil innehåller komprimerade data i gzip eller deflate format och dess innehållskodning anges i enlighet med detta skiljer sig nedladdningsbeteendet mellan Node.js och webbläsare. I Node.js kommer lagringsklienter att ladda ned filen i komprimerat format, medan data i webbläsare laddas ned i komprimerat format.

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i Node.js

Auktorisering av delad nyckel baserat på kontonamn och kontonyckel
- StorageSharedKeyCredential
Generering av signatur för delad åtkomst (SAS)
- generateAccountSASQueryParameters()
- generateDataLakeSASQueryParameters()
Parallell uppladdning och nedladdning. Observera att DataLakeFileClient.upload() finns i både Node.js och webbläsare.
- DataLakeFileClient.uploadFile()
- DataLakeFileClient.uploadStream()
- DataLakeFileClient.readToBuffer()
- DataLakeFileClient.readToFile()

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i webbläsare

Ej tillämpligt

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

CORS

Du måste konfigurera CORS (Cross-Origin Resource Sharing) regler för ditt lagringskonto om du behöver utveckla för webbläsare. Gå till Azure-portalen och Azure Storage Explorer, leta reda på ditt lagringskonto, skapa nya CORS-regler för blob/kö/fil/tabelltjänster.

Du kan till exempel skapa följande CORS-inställningar för felsökning. Men anpassa inställningarna noggrant enligt dina krav i produktionsmiljön.

Tillåtet ursprung: *
Tillåtna verb: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Tillåtna rubriker: *
Synliga rubriker: *
Maximal ålder (sekunder): 86400

Obs! Data Lake delar för närvarande CORS-inställningar för blobtjänsten.

Viktiga begrepp

Azure Data Lake Storage Gen2 har utformats för att:

Hantera flera petabyte med information samtidigt som hundratals gigabit dataflöde bibehålls
Gör att du enkelt kan hantera enorma mängder data

Viktiga funktioner i DataLake Storage Gen2 är:

Hadoop-kompatibel åtkomst
En superuppsättning POSIX-behörigheter
Kostnadseffektivt när det gäller lagringskapacitet och transaktioner till låg kostnad
Optimerad drivrutin för stordataanalys

En grundläggande del av Data Lake Storage Gen2 är att lägga till ett hierarkiskt namnområde i Blob Storage. Det hierarkiska namnområdet organiserar objekt/filer i en hierarki med kataloger för effektiv dataåtkomst.

Tidigare var molnbaserad analys tvungen att kompromissa när det gäller prestanda, hantering och säkerhet. Data Lake Storage Gen2 hanterar var och en av dessa aspekter på följande sätt:

Prestanda optimeras eftersom du inte behöver kopiera eller transformera data som en förutsättning för analys. Det hierarkiska namnområdet förbättrar avsevärt prestandan för kataloghanteringsåtgärder, vilket förbättrar den övergripande jobbprestandan.
Det är enklare att hantera eftersom du kan organisera och manipulera filer via kataloger och underkataloger.
Säkerhet kan tillämpas eftersom du kan definiera POSIX-behörigheter för kataloger eller enskilda filer.
Kostnadseffektivitet möjliggörs eftersom Data Lake Storage Gen2 bygger på azure bloblagring till låg kostnad. De ytterligare funktionerna sänker ytterligare den totala ägandekostnaden för att köra stordataanalys i Azure.

Data Lake Storage erbjuder tre typer av resurser:

Det lagringskontot som används via DataLakeServiceClient
Ett filsystem i lagringskontot som används via DataLakeFileSystemClient
En sökväg i ett filsystem som används via DataLakeDirectoryClient eller DataLakeFileClient

Azure DataLake Gen2	Klick
Filsystem	Behållare
Sökväg (fil eller katalog)	Klick

Obs! Det här klientbiblioteket stöder endast lagringskonton med hierarkisk namnrymd (HNS) aktiverat.

Exempel

Importera paketet
Skapa data lake-tjänstklienten
Skapa ett nytt filsystem
Lista filsystemen
Skapa och ta bort en katalog
Skapa en fil
Lista sökvägar i ett filsystem
Ladda ned en fil och konvertera den till en sträng (Node.js)
Ladda ned en fil och konvertera den till en sträng (webbläsare)

Importera paketet

Om du vill använda klienterna importerar du paketet till filen:

const AzureStorageDataLake = require("@azure/storage-file-datalake");

Alternativt kan du selektivt importera endast de typer som du behöver:

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

Skapa data lake-tjänstklienten

DataLakeServiceClient kräver en URL till data lake-tjänsten och en åtkomstautentiseringsuppgift. Du kan också välja att acceptera vissa inställningar i parametern options.

med `DefaultAzureCredential` från `@azure/identity`-paketet

Rekommenderat sätt att instansiera en DataLakeServiceClient

Märka. Azure Data Lake återanvänder för närvarande blobrelaterade roller som "Storage Blob Data Owner" under följande AAD OAuth-autentisering.

Installation : Referens – Auktorisera åtkomst till blobar (data lake) och köer med Azure Active Directory från ett klientprogram – /azure/storage/common/storage-auth-aad-app

Registrera ett nytt AAD-program och ge behörighet att komma åt Azure Storage för den inloggade användarens räkning.
- Registrera ett nytt program i Azure Active Directory (i azure-portalen) – /azure/active-directory/develop/quickstart-register-app
- I avsnittet API permissions väljer du Add a permission och väljer Microsoft APIs.
- Välj Azure Storage och markera kryssrutan bredvid user_impersonation och klicka sedan på Add permissions. Detta skulle göra det möjligt för programmet att komma åt Azure Storage för den inloggade användarens räkning.
Bevilja åtkomst till Azure Data Lake-data med RBAC i Azure-portalen
- RBAC-roller för blobar (datasjö) och köer – /azure/storage/common/storage-auth-aad-rbac-portal.
- I Azure-portalen går du till ditt lagringskonto och tilldelar Storage Blob Data Contributor roll till det registrerade AAD-programmet från fliken Access control (IAM) (i navigeringsfältet till vänster i ditt lagringskonto i Azure-portalen).
Miljökonfiguration för exemplet
- På översiktssidan för ditt AAD-program noterar du CLIENT ID och TENANT ID. På fliken "Certifikat & hemligheter" skapar du en hemlighet och noterar den nedåt.
- Kontrollera att du har AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET som miljövariabler för att köra exemplet (Kan utnyttja process.env).

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@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
);

Se Azure AD Auth-exempel för ett fullständigt exempel med den här metoden.

[Obs! Stegen ovan gäller endast för Node.js]

använda anslutningssträng

Du kan också instansiera en DataLakeServiceClient med hjälp av den fromConnectionString() statiska metoden med den fullständiga anslutningssträngen som argument. (Anslutningssträngen kan hämtas från Azure-portalen.) [ENDAST TILLGÄNGLIGT I NODE.JS RUNTIME]

const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

med `StorageSharedKeyCredential`

Du kan också instansiera en DataLakeServiceClient med en StorageSharedKeyCredential genom att skicka kontonamn och kontonyckel som argument. (Kontonamnet och kontonyckeln kan hämtas från Azure-portalen.) [ENDAST TILLGÄNGLIGT I NODE.JS RUNTIME]

const {
  DataLakeServiceClient,
  StorageSharedKeyCredential
} = require("@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
);

med SAS-token

Du kan också instansiera en DataLakeServiceClient med en signatur för delad åtkomst (SAS). Du kan hämta SAS-token från Azure-portalen eller generera en med hjälp av generateAccountSASQueryParameters().

const { DataLakeServiceClient } = require("@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}`
);

Skapa ett nytt filsystem

Använd DataLakeServiceClient.getFileSystemClient() för att hämta en filsystemklientinstans och skapa sedan en ny filsystemresurs.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  // 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);
}

main();

Visa en lista över filsystemen

Använd DataLakeServiceClient.listFileSystems()-funktionen för att iterera filsystemen med den nya for-await-of syntaxen:

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Alternativt utan att använda for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  let i = 1;
  const iter = datalakeServiceClient.listFileSystems();
  let fileSystemItem = await iter.next();
  while (!fileSystemItem.done) {
    console.log(`File System ${i++}: ${fileSystemItem.value.name}`);
    fileSystemItem = await iter.next();
  }
}

main();

Dessutom stöds sidnumrering även för listning via byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  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}`);
      }
    }
  }
}

main();

Skapa och ta bort en katalog

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
  const directoryClient = fileSystemClient.getDirectoryClient("directory");
  await directoryClient.create();
  await directoryClient.delete();
}

main();

Skapa en fil

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";

async function main() {
  const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

  const content = "Hello world!";
  const fileName = "newfile" + new Date().getTime();
  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`);
}

main();

Lista sökvägar i ett filsystem

Liknar listning av filsystem.

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";

async function main() {
  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}`);
  }
}

main();

Ladda ned en fil och konvertera den till en sträng (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { DataLakeServiceClient } = require("@azure/storage-file-datalake");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const fileSystemName = "<file system name>";
const fileName = "<file name>";

async function main() {
  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();
  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) {
    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();

Ladda ned en fil och konvertera den till en sträng (webbläsare)

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

async function main() {
  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();
  const downloaded = await blobToString(await downloadResponse.contentAsBlob);
  console.log(
    "Downloaded file 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();

Felsökning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Nästa steg

Fler kodexempel:

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

visningar

Dela via

Azure Storage File Data Lake-klientbibliotek för JavaScript – version 12.25.0

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

Installera paketet

Autentisera klienten

Azure Active Directory

Kompatibilitet

Webbarbetare

Skillnader mellan Node.js och webbläsare

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i Node.js

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i webbläsare

JavaScript-paket

CORS

Viktiga begrepp

Exempel

Importera paketet

Skapa data lake-tjänstklienten

med `DefaultAzureCredential` från `@azure/identity`-paketet

använda anslutningssträng

med `StorageSharedKeyCredential`

med SAS-token

Skapa ett nytt filsystem

Visa en lista över filsystemen

Skapa och ta bort en katalog

Skapa en fil

Lista sökvägar i ett filsystem

Ladda ned en fil och konvertera den till en sträng (Node.js)

Ladda ned en fil och konvertera den till en sträng (webbläsare)

Felsökning

Nästa steg

Bidragande

Ytterligare resurser

Dela via

Azure Storage File Data Lake-klientbibliotek för JavaScript – version 12.25.0

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

Installera paketet

Autentisera klienten

Azure Active Directory

Kompatibilitet

Webbarbetare

Skillnader mellan Node.js och webbläsare

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i Node.js

Funktioner, gränssnitt, klasser eller funktioner som endast är tillgängliga i webbläsare

JavaScript-paket

CORS

Viktiga begrepp

Exempel

Importera paketet

Skapa data lake-tjänstklienten

med DefaultAzureCredential från @azure/identity-paketet

använda anslutningssträng

med StorageSharedKeyCredential

med SAS-token

Skapa ett nytt filsystem

Visa en lista över filsystemen

Skapa och ta bort en katalog

Skapa en fil

Lista sökvägar i ett filsystem

Ladda ned en fil och konvertera den till en sträng (Node.js)

Ladda ned en fil och konvertera den till en sträng (webbläsare)

Felsökning

Nästa steg

Bidragande

Ytterligare resurser

med `DefaultAzureCredential` från `@azure/identity`-paketet

med `StorageSharedKeyCredential`