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

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

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

Pomocí klientských knihoven v tomto balíčku:

• Create, výpis nebo odstranění systémů souborů
• Create/Čtení/Seznam/Aktualizace/Odstranění cest, adresářů a souborů

klíčové odkazy:

• Zdrojový kód
• Balíček (npm)
• Referenční dokumentace k rozhraní API
• Produktová dokumentace
• ukázky
• Rozhraní REST API služby Azure Storage Data Lake

Začínáme

Aktuálně podporovaná prostředí

• LtS verze Node.js
• Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

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

Požadavky

• Předplatné Azure
• Účet úložiště

Instalace balíčku

Upřednostňovaným způsobem, jak nainstalovat klientskou knihovnu Azure Storage Data Lake pro JavaScript, je použít 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í. Abyste mohli pracovat se službou Azure Data Lake Storage, budete muset vytvořit instanci klienta úložiště , DataLakeServiceClientDataLakeFileSystemClientnebo DataLakePathClient například . Další informace o ověřování najdete v DataLakeServiceClientukázkách pro vytvoření.

• Azure Active Directory
• Sdílený klíč
• Sdílené přístupové podpisy

Azure Active Directory

Služba Azure Data Lake Storage podporuje použití Azure Active Directory k ověřování požadavků na rozhraní API. Balíček @azure/identity poskytuje různé typy přihlašovacích údajů, které k tomu může vaše aplikace použít. Další podrobnosti a ukázky, které vám pomůžou začít, najdete v souboru README @azure/identity .

Kompatibilita

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 prohlížečů Chrome, Firefox a Edge.

Pracovní procesy webu

Tato knihovna vyžaduje, aby určité objekty MODELU DOM byly při použití v prohlížeči globálně dostupné, což webové pracovní procesy ve výchozím nastavení nezpřístupní. Aby tato knihovna fungovala ve webových pracovních pracovních činnostech, budete je muset polyfillovat.

Další informace najdete v naší dokumentaci k používání sady Azure SDK pro JS ve webových pracovních prostředích.

Tato knihovna závisí na následujících rozhraních API dom, která při použití ve webových pracovních procesů vyžadují načtení externích polyfillů:

• document
• DOMParser
• Node
• XMLSerializer

Rozdíly mezi Node.js a prohlížeči

Mezi Node.js a modulem runtime prohlížeče existují rozdíly. Při začátcích s touto knihovnou věnujte pozornost rozhraním API nebo třídám označeným jako "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "POUZE K DISPOZICI V PROHLÍŽEČÍCH".

• Pokud soubor obsahuje komprimovaná data ve gzip formátu nebo deflate a jeho kódování obsahu je odpovídajícím způsobem nastaveno, chování stahování se mezi Node.js a prohlížeči liší. V Node.js storage klienti stáhnou soubor v 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 v prohlížečích.
  • DataLakeFileClient.uploadFile()
  • DataLakeFileClient.uploadStream()
  • DataLakeFileClient.readToBuffer()
  • DataLakeFileClient.readToFile()

Funkce, rozhraní, třídy nebo funkce dostupné pouze v prohlížečích

• –

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu používat 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 pro prohlížeče, musíte pro svůj účet úložiště nastavit pravidla sdílení prostředků mezi zdroji (CORS ). Přejděte na Azure Portal a Průzkumník služby Azure Storage, vyhledejte svůj účet úložiště a vytvořte nová pravidla CORS pro objekty blob, fronty, soubory nebo table služby.

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é zdroje: *
• Povolené operace: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Povolené hlavičky: *
• Vystavené hlavičky: *
• Maximální věk (sekundy): 86400

Poznámka: Data Lake v současné době sdílí nastavení CORS pro službu Blob Service.

Klíčové koncepty

Azure Data Lake Storage Gen2 byl navržen tak, aby:

• Poskytování 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í Data Lake Storage Gen2 je přidání hierarchického oboru názvů do služby Blob Storage. Hierarchický obor názvů uspořádá objekty nebo 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 každý z těchto aspektů řeší následujícími způsoby:

• Výkon je optimalizovaný, protože nemusíte 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 vynutitelné, protože můžete definovat oprávnění POSIX pro adresáře nebo jednotlivé soubory.
• Nákladová efektivita je možná, protože Data Lake Storage Gen2 je postavená na nízkonákladovém úložišti Objektů blob Azure. Další funkce dále snižují celkové náklady na vlastnictví při 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ě, který se používá prostřednictvímDataLakeFileSystemClient
• Cesta v systému souborů používaná prostřednictvím DataLakeDirectoryClient neboDataLakeFileClient

Azure DataLake Gen2	Objekt blob
Filesystem	Kontejner
Cesta (soubor nebo adresář)	Objekt blob

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

Příklady

• Import balíčku
• Create klienta služby Data Lake
• Create nového systému souborů
• Výpis systémů souborů
• Create a odstranění adresáře
• Create souboru
• Výpis cest uvnitř systému souborů
• Stažení souboru a jeho převedení na řetězec (Node.js)
• Stažení souboru a jeho převedení na řetězec (prohlížeče)

Import balíčku

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

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

Případně můžete selektivně importovat pouze typy, které potřebujete:

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

Create klienta služby Data Lake

Vyžaduje DataLakeServiceClient 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 balíčkem DefaultAzureCredential z @azure/identity

Doporučený způsob vytvoření instance DataLakeServiceClient

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

Nastavení: Referenční informace – Autorizace přístupu k objektům blob (Data Lake) a frontám pomocí Azure Active Directory z klientské aplikace – /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 (na webu azure-portal) – /azure/active-directory/develop/quickstart-register-app
  • API permissions V části 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 (Data Lake) a fronty – /azure/storage/common/storage-auth-aad-rbac-portal.
  • Na webu Azure Portal přejděte ke svému účtu úložiště a přiřaďte zaregistrované aplikaci AAD roli Přispěvatel dat v objektech blob služby Storage z Access control (IAM) karty (v levém navigačním panelu vašeho účtu úložiště na webu azure-portal).

• Nastavení prostředí pro ukázku

  • Na stránce přehledu vaší 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í, abyste mohli ukázku úspěšně spustit (může využít 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
);

Úplný příklad použití této metody najdete v ukázce ověřování Azure AD.

[Poznámka: Výše uvedené kroky jsou určené jenom pro Node.js.

pomocí připojovací řetězec

Alternativně můžete vytvořit DataLakeServiceClient instanci pomocí fromConnectionString() statické metody s úplným připojovací řetězec jako argumentem. (Připojovací řetězec můžete získat z webu Azure Portal.) [K DISPOZICI POUZE V NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

S StorageSharedKeyCredential

Případně můžete vytvořit instanci DataLakeServiceClient s argumentem StorageSharedKeyCredential account-name (název účtu) a account-key (klíč účtu) jako argumenty. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V 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
);

s tokenem SAS

Můžete také vytvořit DataLakeServiceClient instanci se sdílenými přístupovými podpisy (SAS). Token SAS můžete získat z webu Azure Portal nebo ho vygenerovat pomocí 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}`
);

Create nového systému souborů

Použijte DataLakeServiceClient.getFileSystemClient() k získání instance klienta systému souborů a pak vytvořte nový prostředek systému souborů.

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

Výpis systémů souborů

K iteraci systémů souborů použijte DataLakeServiceClient.listFileSystems() funkci s novou for-await-of syntaxí:

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;
  let fileSystems = datalakeServiceClient.listFileSystems();
  for await (const fileSystem of fileSystems) {
    console.log(`File system ${i++}: ${fileSystem.name}`);
  }
}

main();

Alternativně bez použití 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;
  let iter = datalakeServiceClient.listFileSystems();
  let fileSystemItem = await iter.next();
  while (!fileSystemItem.done) {
    console.log(`File System ${i++}: ${fileSystemItem.value.name}`);
    fileSystemItem = await iter.next();
  }
}

main();

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

Create a odstranění adresáře

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

Vytvoření souboru

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

Výpis cest uvnitř systému souborů

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

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;
  let paths = fileSystemClient.listPaths();
  for await (const path of paths) {
    console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
  }
}

main();

Stažení souboru a jeho převedení na řetězec (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();

Stažení souboru a jeho převedení na řetězec (prohlížeče)

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: Blob): Promise<string> {
    const fileReader = new FileReader();
    return new Promise<string>((resolve, reject) => {
      fileReader.onloadend = (ev: any) => {
        resolve(ev.target!.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Poradce při potížích

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

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

setLogLevel("info");

Další kroky

Další ukázky kódu:

• Ukázky úložiště DataLake (JavaScript)
• Ukázky úložiště DataLake (TypeScript)
• Testovací případy služby DataLake Storage

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.