Sdílet prostřednictvím

Klientská knihovna Azure Storage File Data Lake pro JavaScript – verze 12.28.1

Azure Data Lake Storage (ADLS) zahrnuje všechny možnosti potřebné k tomu, aby vývojáři, datoví vědci a analytici mohli ukládat data libovolné velikosti, tvaru a rychlosti a provádět všechny typy zpracování a analýzy napříč platformami a jazyky. Odstraňuje složitost ingestování a ukládání všech vašich dat a zároveň usnadňuje zprovoznění dávkové, streamované a interaktivní analýzy.

Tento projekt poskytuje klientskou knihovnu v JavaScriptu, která usnadňuje využívání služby Microsoft Azure Storage Data Lake.

Klientské knihovny v tomto balíčku slouží k:

  • Vytvoření, výpis nebo odstranění systémů souborů
  • Vytváření, čtení, seznam, aktualizace, odstranění cest, adresářů a souborů

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

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

Prerequisites

Instalace balíčku

Upřednostňovaným způsobem instalace klientské knihovny Azure Storage Data Lake pro JavaScript je použití správce balíčků npm. Do okna terminálu zadejte následující:

npm install @azure/storage-file-datalake

Ověření klienta

Azure Storage podporuje několik způsobů ověřování. Pokud chcete pracovat se službou Azure Data Lake Storage, musíte například vytvořit instanci klienta služby Storage – DataLakeServiceClient, DataLakeFileSystemClientnebo DataLakePathClient. Další informace o ověřování najdete v ukázkách pro vytvoření DataLakeServiceClient.

Azure Active Directory

Služba Azure Data Lake 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 soubor obsahuje komprimovaná data ve formátu gzip nebo deflate a jeho kódování obsahu je nastavené odpovídajícím způsobem, chování při stahování se liší mezi Node.js a prohlížeči. V Node.js klienti úložiště stáhnou soubor v jeho 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()
    • generateDataLakeSASQueryParameters()
  • Paralelní nahrávání a stahování Všimněte si, že DataLakeFileClient.upload() je k dispozici v Node.js i prohlížečích.
    • DataLakeFileClient.uploadFile()
    • DataLakeFileClient.uploadStream()
    • DataLakeFileClient.readToBuffer()
    • DataLakeFileClient.readToFile()
Funkce, rozhraní, třídy nebo funkce dostupné pouze v prohlížečích
  • N/A

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

Poznámka: Data Lake aktuálně sdílí nastavení CORS pro službu Blob Service.

Klíčové koncepty

Služba Azure Data Lake Storage Gen2 byla navržena tak, aby:

  • Obsluha několika petabajtů informací při zachování stovek gigabitů propustnosti
  • Umožňuje snadnou správu obrovských objemů dat.

Mezi klíčové funkce DataLake Storage Gen2 patří:

  • Přístup kompatibilní s Hadoopem
  • Super sada oprávnění POSIX
  • Nákladově efektivní z hlediska nízkonákladové kapacity úložiště a transakcí
  • Optimalizovaný ovladač pro analýzu velkých objemů dat

Základní součástí Služby Data Lake Storage Gen2 je přidání hierarchického oboru názvů do úložiště objektů blob. Hierarchický obor názvů uspořádá objekty a soubory do hierarchie adresářů pro efektivní přístup k datům.

V minulosti musely cloudové analýzy ohrozit výkon, správu a zabezpečení. Data Lake Storage Gen2 řeší každý z těchto aspektů následujícími způsoby:

  • Výkon je optimalizovaný, protože není nutné kopírovat ani transformovat data jako předpoklad pro analýzu. Hierarchický obor názvů výrazně zlepšuje výkon operací správy adresářů, což zlepšuje celkový výkon úloh.
  • Správa je jednodušší, protože soubory můžete uspořádat a manipulovat s nimi prostřednictvím adresářů a podadresářů.
  • Zabezpečení je vynucovatelné, protože můžete definovat oprávnění POSIX pro adresáře nebo jednotlivé soubory.
  • Efektivita nákladů je možná, protože Služba Data Lake Storage Gen2 je postavená na nízkonákladovém úložišti objektů blob v Azure. Další funkce dále snižují celkové náklady na vlastnictví pro spouštění analýz velkých objemů dat v Azure.

Data Lake Storage nabízí tři typy prostředků:

  • Účet úložiště použitý prostřednictvímDataLakeServiceClient
  • Systém souborů v účtu úložiště používaný prostřednictvím DataLakeFileSystemClient
  • Cesta v souborovém systému použitá pomocí DataLakeDirectoryClient neboDataLakeFileClient
Azure DataLake Gen2 Blob
Filesystem Container
Cesta (soubor nebo adresář) Blob

Poznámka: Tato klientská knihovna podporuje pouze účty úložiště s povoleným hierarchickým oborem názvů (HNS).

Examples

Import balíčku

Pokud chcete použít klienty, naimportujte balíček do souboru:

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

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

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

Vytvoření klienta služby Data Lake

DataLakeServiceClient vyžaduje adresu URL služby Data Lake 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 DataLakeServiceClient

Notice. Azure Data Lake v současné době během ověřování AAD OAuth opakovaně používá role související s objekty blob, jako je Vlastník dat v objektech blob služby Storage.

Nastavení : Reference – Autorizace přístupu k objektům blob (datové jezero) a frontám pomocí Azure Active Directory z klientské aplikace – https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

  • Zaregistrujte novou aplikaci AAD a udělte 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 Azure Data Lake pomocí RBAC na webu Azure Portal

    • Role RBAC pro objekty blob (datové jezero) 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 { 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,
);

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

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

s StorageSharedKeyCredential

Alternativně vytvoříte instanci DataLakeServiceClient 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, 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,
);

s tokenem SAS

Můžete také vytvořit instanci DataLakeServiceClient 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 { 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}`,
);

Vytvoření nového systému souborů

Pomocí DataLakeServiceClient.getFileSystemClient() získejte instanci klienta systému souborů a pak vytvořte nový prostředek systému souborů.

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

Výpis systémů souborů

Pomocí funkce DataLakeServiceClient.listFileSystems() iterujte systémy souborů s novou syntaxí for-await-of:

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

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

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

Kromě toho se stránkování podporuje také pro výpis prostřednictvím 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}`);
    }
  }
}

Vytvoření a odstranění adresáře

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

Vytvoření souboru

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

Výpis cest uvnitř systému souborů

Podobá se výpisu systémů souborů.

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

Stáhněte soubor a převeďte ho na řetězec (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);
  });
}

Stáhněte si soubor a převeďte ho na řetězec (prohlížeče).

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

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.

  • Last updated on