Azure Storage File Data Lake-clientbibliotheek voor JavaScript - versie 12.25.0

Artikel
11/20/2024

Azure Data Lake Storage (ADLS) bevat alle mogelijkheden die nodig zijn voor ontwikkelaars, gegevenswetenschappers en analisten om gegevens van elke grootte, vorm en snelheid op te slaan en alle soorten verwerking en analyse op verschillende platforms en talen uit te voeren. Het verwijdert de complexiteit van het opnemen en opslaan van al uw gegevens, terwijl u deze sneller kunt uitvoeren met batch-, streaming- en interactieve analyses.

Dit project biedt een clientbibliotheek in JavaScript waarmee u de Microsoft Azure Storage Data Lake-service eenvoudig kunt gebruiken.

Gebruik de clientbibliotheken in dit pakket om:

Bestandssystemen maken/weergeven/verwijderen
Paden, mappen en bestanden maken/lezen/weergeven/bijwerken/verwijderen

sleutelkoppelingen:

Slag

Momenteel ondersteunde omgevingen

LTS-versies van Node.js
Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

Een Azure-abonnement
Een -opslagaccount

Het pakket installeren

De voorkeursmethode voor het installeren van de Azure Storage Data Lake-clientbibliotheek voor JavaScript is het gebruik van npm-pakketbeheer. Typ het volgende in een terminalvenster:

npm install @azure/storage-file-datalake

De client verifiëren

Azure Storage ondersteunt verschillende manieren om te verifiëren. Als u wilt communiceren met de Azure Data Lake Storage-service, moet u bijvoorbeeld een exemplaar van een Storage-client maken: DataLakeServiceClient, DataLakeFileSystemClientof DataLakePathClient. Zie voorbeelden voor het maken van de DataLakeServiceClient voor meer informatie over verificatie.

Azure Active Directory
gedeelde sleutel
handtekeningen voor gedeelde toegang

Azure Active Directory

De Azure Data Lake Storage-service ondersteunt het gebruik van Azure Active Directory voor het verifiëren van aanvragen voor de API's. Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. Raadpleeg de LEESMIJ voor @azure/identity voor meer informatie en voorbeelden om u op weg te helpen.

Compatibiliteit

Deze bibliotheek is compatibel met Node.js en browsers en gevalideerd op basis van LTS-Node.js versies (>=8.16.0) en de nieuwste versies van Chrome, Firefox en Edge.

Webmedewerkers

Voor deze bibliotheek moeten bepaalde DOM-objecten wereldwijd beschikbaar zijn wanneer ze worden gebruikt in de browser, die webmedewerkers niet standaard beschikbaar maken. U moet deze invullen om deze bibliotheek in webwerkrollen te laten werken.

Raadpleeg onze documentatie voor het gebruik van Azure SDK voor JS in Web Workers voor meer informatie

Deze bibliotheek is afhankelijk van de volgende DOM-API's waarvoor externe polyfills moeten worden geladen wanneer ze worden gebruikt in webwerkrollen:

Verschillen tussen Node.js en browsers

Er zijn verschillen tussen Node.js en runtime van browsers. Wanneer u aan de slag gaat met deze bibliotheek, moet u letten op API's of klassen die zijn gemarkeerd met 'ONLY AVAILABLE IN NODE.JS RUNTIME' of 'ONLY AVAILABLE IN BROWSERS'.

Als een bestand gecomprimeerde gegevens in gzip of deflate-indeling bevat en de inhoudscodering dienovereenkomstig is ingesteld, is het downloaden van gedrag anders tussen Node.js en browsers. In Node.js-opslagclients wordt het bestand in de gecomprimeerde indeling gedownload, terwijl in browsers de gegevens worden gedownload in gedeprimeerde indeling.

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in Node.js

Autorisatie van gedeelde sleutels op basis van accountnaam en accountsleutel
- StorageSharedKeyCredential
Sas-generatie (Shared Access Signature)
- generateAccountSASQueryParameters()
- generateDataLakeSASQueryParameters()
Parallel uploaden en downloaden. Houd er rekening mee dat DataLakeFileClient.upload() beschikbaar is in zowel Node.js als browsers.
- DataLakeFileClient.uploadFile()
- DataLakeFileClient.uploadStream()
- DataLakeFileClient.readToBuffer()
- DataLakeFileClient.readToFile()

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in browsers

N.V.T

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

CORS

U moet CORS-regels (Cross-Origin Resource Sharing) instellen regels voor uw opslagaccount als u voor browsers moet ontwikkelen. Ga naar Azure Portal en Azure Storage Explorer, zoek uw opslagaccount, maak nieuwe CORS-regels voor blob/queue/file/table-service(s).

U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Maar pas de instellingen zorgvuldig aan op basis van uw vereisten in de productieomgeving.

Toegestane oorsprongen: *
Toegestane werkwoorden: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Toegestane headers: *
Weergegeven headers: *
Maximale leeftijd (seconden): 86400

Opmerking: Data Lake deelt momenteel CORS-instellingen voor de blobservice.

Sleutelbegrippen

Azure Data Lake Storage Gen2 is ontworpen voor:

Meerdere petabytes aan informatie leveren terwijl honderden gigabits aan doorvoer worden ondersteund
Hiermee kunt u eenvoudig enorme hoeveelheden gegevens beheren

Belangrijke functies van DataLake Storage Gen2 zijn:

Hadoop-compatibele toegang
Een superset POSIX-machtigingen
Rendabel in termen van voordelige opslagcapaciteit en transacties
Geoptimaliseerd stuurprogramma voor big data-analyse

Een fundamenteel onderdeel van Data Lake Storage Gen2 is het toevoegen van een hiërarchische naamruimte aan Blob Storage. De hiërarchische naamruimte organiseert objecten/bestanden in een hiërarchie van mappen voor efficiënte gegevenstoegang.

In het verleden moesten analyses in de cloud inbreuk maken op het gebied van prestaties, beheer en beveiliging. Data Lake Storage Gen2 behandelt elk van deze aspecten op de volgende manieren:

Prestaties zijn geoptimaliseerd omdat u gegevens niet hoeft te kopiëren of transformeren als een vereiste voor analyse. De hiërarchische naamruimte verbetert de prestaties van directorybeheerbewerkingen aanzienlijk, waardoor de algehele taakprestaties worden verbeterd.
Beheer is eenvoudiger omdat u bestanden kunt organiseren en bewerken via mappen en submappen.
Beveiliging kan worden afgedwongen omdat u POSIX-machtigingen voor mappen of afzonderlijke bestanden kunt definiëren.
Kosteneffectiviteit wordt mogelijk gemaakt omdat Data Lake Storage Gen2 is gebouwd op basis van de goedkope Azure Blob Storage. De extra functies verlagen de totale eigendomskosten voor het uitvoeren van big data-analyses in Azure verder.

Data Lake Storage biedt drie typen resources:

Het -opslagaccount dat via DataLakeServiceClient wordt gebruikt
Een bestandssysteem in het opslagaccount dat via DataLakeFileSystemClient wordt gebruikt
Een pad in een bestandssysteem dat wordt gebruikt via DataLakeDirectoryClient of DataLakeFileClient

Azure DataLake Gen2	Blob
Bestandssysteem	Container
Pad (bestand of map)	Blob

Opmerking: deze clientbibliotheek ondersteunt alleen opslagaccounts waarvoor HNS (hiërarchische naamruimte) is ingeschakeld.

Voorbeelden

het pakket importeren
De Data Lake Service-client maken
Een nieuw bestandssysteem maken
De bestandssystemen weergeven
een map maken en verwijderen
Een bestand maken
lijstpaden in een bestandssysteem
Een bestand downloaden en converteren naar een tekenreeks (Node.js)
een bestand downloaden en converteren naar een tekenreeks (browsers)

Het pakket importeren

Als u de clients wilt gebruiken, importeert u het pakket in uw bestand:

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

U kunt ook selectief alleen de typen importeren die u nodig hebt:

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

De Data Lake Service-client maken

De DataLakeServiceClient vereist een URL naar de Data Lake-service en een toegangsreferentie. Het accepteert desgewenst ook bepaalde instellingen in de parameter options.

met `DefaultAzureCredential` uit `@azure/identity` pakket

Aanbevolen manier om een DataLakeServiceClient te instantiëren

Bemerken. Azure Data Lake hergebruikt momenteel blob-gerelateerde rollen, zoals 'Eigenaar van opslagblobgegevens' tijdens het volgen van AAD OAuth-verificatie.

Installatie: Naslaginformatie - Toegang tot blobs (data lake) en wachtrijen autoriseren met Azure Active Directory vanuit een clienttoepassing - /azure/storage/common/storage-auth-aad-app

Registreer een nieuwe AAD-toepassing en geef machtigingen voor toegang tot Azure Storage namens de aangemelde gebruiker.
- Een nieuwe toepassing registreren in Azure Active Directory (in azure-portal) - /azure/active-directory/develop/quickstart-register-app
- Selecteer Add a permission in de sectie API permissions en kies Microsoft APIs.
- Kies Azure Storage en schakel het selectievakje naast user_impersonation in en klik vervolgens op Add permissions. Hierdoor heeft de toepassing namens de aangemelde gebruiker toegang tot Azure Storage.
Toegang verlenen tot Azure Data Lake-gegevens met RBAC in Azure Portal
- RBAC-rollen voor blobs (data lake) en wachtrijen - /azure/storage/common/storage-auth-aad-rbac-portal.
- Ga in azure Portal naar uw opslagaccount en wijs rol Inzender voor opslagblobgegevens toe aan de geregistreerde AAD-toepassing vanaf Access control (IAM) tabblad (in de navigatiebalk aan de linkerkant van uw opslagaccount in azure-portal).
Omgeving instellen voor het voorbeeld
- Noteer op de overzichtspagina van uw AAD-toepassing de CLIENT ID en TENANT ID. Maak op het tabblad Certificaten & Geheimen een geheim en noteer dat.
- Zorg ervoor dat u AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET als omgevingsvariabelen om het voorbeeld uit te voeren (kan gebruikmaken van 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
);

Zie het Azure AD-verificatievoorbeeld voor een volledig voorbeeld met behulp van deze methode.

[Opmerking: bovenstaande stappen zijn alleen bedoeld voor Node.js]

verbindingsreeks gebruiken

U kunt ook een DataLakeServiceClient maken met behulp van de statische methode fromConnectionString() met de volledige verbindingsreeks als argument. (De verbindingsreeks kan worden verkregen via azure Portal.) [ALLEEN BESCHIKBAAR IN NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

met `StorageSharedKeyCredential`

U kunt ook een DataLakeServiceClient maken met een StorageSharedKeyCredential door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en accountsleutel kunnen worden verkregen via de Azure-portal.) [ALLEEN BESCHIKBAAR IN 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
);

met SAS-token

U kunt ook een DataLakeServiceClient maken met shared access signatures (SAS). U kunt het SAS-token ophalen uit azure Portal of er een genereren met behulp van 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}`
);

Een nieuw bestandssysteem maken

Gebruik DataLakeServiceClient.getFileSystemClient() om een bestandssysteemclientexemplaren op te halen en vervolgens een nieuwe bestandssysteemresource te maken.

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

De bestandssystemen weergeven

Gebruik DataLakeServiceClient.listFileSystems() functie om de bestandssystemen te herhalen, met de nieuwe for-await-of syntaxis:

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

U kunt ook 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();

Daarnaast wordt paginering ook ondersteund voor vermelding 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();

Een map maken en verwijderen

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

Een bestand maken

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

Paden in een bestandssysteem weergeven

Vergelijkbaar met het weergeven van bestandssystemen.

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

Een bestand downloaden en converteren naar een tekenreeks (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();

Een bestand downloaden en converteren naar een tekenreeks (browsers)

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

Probleemoplossing

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden:

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

indrukken

Delen via

Azure Storage File Data Lake-clientbibliotheek voor JavaScript - versie 12.25.0

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

De client verifiëren

Azure Active Directory

Compatibiliteit

Webmedewerkers

Verschillen tussen Node.js en browsers

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in Node.js

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in browsers

JavaScript-bundel

CORS

Sleutelbegrippen

Voorbeelden

Het pakket importeren

De Data Lake Service-client maken

met `DefaultAzureCredential` uit `@azure/identity` pakket

verbindingsreeks gebruiken

met `StorageSharedKeyCredential`

met SAS-token

Een nieuw bestandssysteem maken

De bestandssystemen weergeven

Een map maken en verwijderen

Een bestand maken

Paden in een bestandssysteem weergeven

Een bestand downloaden en converteren naar een tekenreeks (Node.js)

Een bestand downloaden en converteren naar een tekenreeks (browsers)

Probleemoplossing

Volgende stappen

Bijdragen

Aanvullende resources

Delen via

Azure Storage File Data Lake-clientbibliotheek voor JavaScript - versie 12.25.0

Slag

Momenteel ondersteunde omgevingen

Voorwaarden

Het pakket installeren

De client verifiëren

Azure Active Directory

Compatibiliteit

Webmedewerkers

Verschillen tussen Node.js en browsers

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in Node.js

Functies, interfaces, klassen of functies die alleen beschikbaar zijn in browsers

JavaScript-bundel

CORS

Sleutelbegrippen

Voorbeelden

Het pakket importeren

De Data Lake Service-client maken

met DefaultAzureCredential uit @azure/identity pakket

verbindingsreeks gebruiken

met StorageSharedKeyCredential

met SAS-token

Een nieuw bestandssysteem maken

De bestandssystemen weergeven

Een map maken en verwijderen

Een bestand maken

Paden in een bestandssysteem weergeven

Een bestand downloaden en converteren naar een tekenreeks (Node.js)

Een bestand downloaden en converteren naar een tekenreeks (browsers)

Probleemoplossing

Volgende stappen

Bijdragen

Aanvullende resources

met `DefaultAzureCredential` uit `@azure/identity` pakket

met `StorageSharedKeyCredential`