Klientská knihovna Azure Storage Data Lake pro JavaScript – verze 12.23.0

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:

• zdrojového kódu
• balíčku (npm)
• Referenční dokumentace k rozhraní API
• dokumentace k produktu
• 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 Safari, Chrome, Edge a Firefox.

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

Požadavky

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

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
• sdílený klíč
• sdílených přístupových podpisů

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.

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 Chromu, Firefoxu a Edge.

Webové pracovní procesy

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ů:

• document
• DOMParser
• Node
• XMLSerializer

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

• Není k dispozici

JavaScript Bundle

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 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ím DataLakeServiceClient
• Systém souborů v účtu úložiště, který se používá prostřednictvím DataLakeFileSystemClient
• Cesta v systému souborů používaná prostřednictvím DataLakeDirectoryClient nebo DataLakeFileClient

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
• Vytvoření klienta služby Data Lake Service
• Vytvoření nového systému souborů
• Zobrazit seznam systémů souborů
• Vytvoření a odstranění adresáře
• Vytvoření souboru
• Seznam cest uvnitř systému souborů
• Stáhnout soubor a převést ho na řetězec (Node.js)
• Stáhnout soubor a převést ho na řetězec (prohlížeče)

Import balíčku

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

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

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

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

Oznámení. 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í: 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
  • 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 (data lake) a fronty – /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).

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

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

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

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]

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

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

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

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ů

Pomocí funkce DataLakeServiceClient.listFileSystems() iterujte systémy souborů s novou syntaxí 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 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();

Vytvoření 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();

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

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

Řešení problémů

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:

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

setLogLevel("info");

Další kroky

Další ukázky kódu:

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

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.