Klientská knihovna Azure Storage File Data Lake pro JavaScript – verze 12.22.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ýzy 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 využívání služby Microsoft Azure Storage Data Lake.
Pomocí klientských knihoven v tomto balíčku:
- Vytvoření, výpis nebo odstranění systémů souborů
- Vytváření, čtení, výpis, aktualizace nebo 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
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 služby Storage, DataLakeServiceClient
například , DataLakeFileSystemClient
nebo DataLakePathClient
. Další informace o ověřování najdete v DataLakeServiceClient
ukázkách pro vytvoření.
Azure Active Directory
Služba Azure Data Lake Storage podporuje použití Azure Active Directory k ověřování požadavků na její 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ů:
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 nebodeflate
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 web 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 řeší každý z těchto aspektů 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 v 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í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
neboDataLakeFileClient
Azure DataLake Gen2 | Objekt blob |
---|---|
Filesystem | Kontejner |
Cesta (soubor nebo adresář) | Objekt blob |
Poznámka: Tato klientská knihovna podporuje jenom úč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
- Vytvoření nového systému souborů
- Výpis systémů souborů
- Vytvoření a odstranění adresáře
- Vytvoření souboru
- Výpis cest v 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, naimportujte balíček do souboru:
const AzureStorageDataLake = require("@azure/storage-file-datalake");
Případně můžete selektivně importovat jenom typy, které potřebujete:
const {
DataLakeServiceClient,
StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");
Vytvoření 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 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 oddílu
API permissions
vyberteAdd a permission
a zvolteMicrosoft APIs
. - Zaškrtněte
Azure Storage
a zaškrtněte políčko vedleuser_impersonation
a klikněte naAdd 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 na svůj účet úložiště a na kartě (v levém navigačním panelu účtu úložiště na webu azure-portal) přiřaďte zaregistrované aplikaci
Access control (IAM)
AAD roli Přispěvatel dat v objektech blob služby Storage.
Nastavení prostředí pro ukázku
- Na stránce přehledu aplikace AAD si poznamenejte
CLIENT ID
aTENANT ID
. Na kartě Certifikáty & tajné kódy vytvořte tajný kód a poznamenejte si ho. - Ujistěte se, že pro úspěšné spuštění ukázky máte AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET jako proměnné prostředí(může využít process.env).
- Na stránce přehledu aplikace AAD si poznamenejte
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ího řetězce
Případně můžete vytvořit instanci DataLakeServiceClient
pomocí fromConnectionString()
statické metody s úplným připojovacím řetězcem jako argumentem. (Připojovací řetězec je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V modulu runtime NODE.JS]
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 a account-key. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V modulu runtime NODE.JS]
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}`
);
Vytvoření 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();
Případně 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 je stránkování podporováno 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 v 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 úložiště DataLake
Přispívání
Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.
Azure SDK for JavaScript
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro