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

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

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

Gebruik de clientbibliotheken in dit pakket voor het volgende:

• bestandssystemen Creatie/lijst/verwijderen
• Creatie/Lezen/Lijst/Bijwerken/Paden, mappen en bestanden verwijderen

belangrijke koppelingen:

• Broncode
• Package (npm)
• API-referentiedocumentatie
• Productdocumentatie
• Voorbeelden
• Azure Storage Data Lake REST API's

Aan de slag

Momenteel ondersteunde omgevingen

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

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

• Een Azure-abonnement
• Een opslagaccount

Het pakket installeren

De beste manier om de Azure Storage Data Lake-clientbibliotheek voor JavaScript te installeren, is het npm-pakketbeheer te gebruiken. 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 een exemplaar van een Storage-client maken, DataLakeServiceClientbijvoorbeeld , DataLakeFileSystemClientofDataLakePathClient. 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 om aanvragen voor de API's te verifiëren. Het @azure/identity pakket biedt verschillende referentietypen die uw toepassing kan gebruiken om dit te doen. Raadpleeg leesmij voor @azure/identity voor meer informatie en voorbeelden om aan de slag te gaan.

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.

Web Workers

Deze bibliotheek vereist dat bepaalde DOM-objecten globaal beschikbaar zijn wanneer ze worden gebruikt in de browser. Deze webwerkrollen maken deze niet standaard beschikbaar. U moet deze invullen om deze bibliotheek te laten werken in webwerkrollen.

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 deze worden gebruikt in webwerkrollen:

• document
• DOMParser
• Node
• XMLSerializer

Verschillen tussen Node.js en browsers

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

• Als een bestand gecomprimeerde gegevens in of-indeling gzipdeflate bevat en de inhoudscodering dienovereenkomstig is ingesteld, verschilt het downloadgedrag tussen Node.js en browsers. In Node.js-opslagclients het bestand in de gecomprimeerde indeling downloaden, terwijl in browsers de gegevens worden gedownload in niet-gecomprimeerde 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 bundler gebruiken. Raadpleeg onze bundeldocumentatie voor meer informatie over hoe u dit doet.

CORS

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

U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Pas de instellingen echter 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.

Belangrijkste concepten

Azure Data Lake Storage Gen2 is ontworpen om:

• Meerdere petabytes aan informatie verwerken met honderden gigabits doorvoer
• Hiermee kunt u eenvoudig enorme hoeveelheden gegevens beheren

Belangrijke functies van DataLake Storage Gen2 zijn onder andere:

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

De toevoeging van een hiërarchische naamruimte aan Blob Storage vormt een fundamenteel onderdeel van Data Lake Storage Gen2. Met de hiërarchische naamruimte worden objecten/bestanden georganiseerd in een hiërarchie met mappen voor efficiënte toegang tot de gegevens.

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

• De prestaties worden geoptimaliseerd omdat u geen gegevens hoeft te kopiëren of transformeren als voorwaarde voor analyse. De hiërarchische naamruimte verbetert de prestaties van directorybeheerbewerkingen aanzienlijk, waardoor de algehele taakprestaties worden verbeterd.
• Het beheer is eenvoudiger omdat u bestanden kunt ordenen en bewerken met behulp van mappen en submappen.
• De beveiliging is afdwingbaar omdat u POSIX-machtigingen kunt definiëren voor structuren of afzonderlijke bestanden.
• Kosteneffectiviteit wordt mogelijk gemaakt omdat Data Lake Storage Gen2 is gebouwd op de goedkope Azure Blob-opslag. De extra functies verlagen de totale beheerkosten voor het uitvoeren van big data-analyses in Azure nog verder.

Data Lake Storage biedt drie typen resources:

• Het opslagaccount dat wordt gebruikt via DataLakeServiceClient
• Een bestandssysteem in het opslagaccount dat wordt gebruikt via DataLakeFileSystemClient
• 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 hiërarchische naamruimte (HNS) is ingeschakeld.

Voorbeelden

• Het pakket importeren
• de data lake-serviceclient Creatie
• een nieuw bestandssysteem Creatie
• De bestandssystemen weergeven
• een map Creatie 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)

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-serviceclient Creatie

De DataLakeServiceClient vereist een URL naar de data lake-service en een toegangsreferentie. Het accepteert optioneel ook enkele instellingen in de options parameter.

met DefaultAzureCredential van @azure/identity pakket

Aanbevolen manier om een instantiëring te maken DataLakeServiceClient

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

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

• Registreer een nieuwe AAD-toepassing en geef namens de aangemelde gebruiker machtigingen voor toegang tot Azure Storage.

  • Een nieuwe toepassing registreren in Azure Active Directory (in de azure-portal) - /azure/active-directory/develop/quickstart-register-app
  • Selecteer Add a permission en kies Microsoft APIsin de API permissions sectie .
  • Selecteer Azure Storage het selectievakje naast user_impersonation en klik op Add permissions. Hierdoor heeft de toepassing toegang tot Azure Storage namens de aangemelde gebruiker.

• 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 de rol Inzender voor opslagblobgegevens toe aan de geregistreerde AAD-toepassing vanaf Access control (IAM) het tabblad (in de linkernavigatiebalk van uw opslagaccount in azure-portal).

• Omgevingsinstellingen 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 hebt om het voorbeeld met succes 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 voorbeeld Azure AD Auth voor een volledig voorbeeld met behulp van deze methode.

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

met behulp van verbindingsreeks

U kunt ook een DataLakeServiceClient instantiëren met behulp van de fromConnectionString() statische methode met de volledige verbindingsreeks als argument. (De verbindingsreeks kunt u verkrijgen 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 instantiëren met een StorageSharedKeyCredential door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en de 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 instantiëren met een SAS (Shared Access Signatures). U kunt het SAS-token ophalen uit de Azure-portal of een token 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 Creatie

Gebruik DataLakeServiceClient.getFileSystemClient() om een exemplaar van een bestandssysteemclient op te halen en maak vervolgens een nieuwe bestandssysteemresource.

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

main();

U kunt ook het volgende doen for-await-ofzonder :

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

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 Creatie 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;
  let 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: 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();

Problemen oplossen

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

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

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden:

• DataLake Storage-voorbeelden (JavaScript)
• Voorbeelden van DataLake Storage (TypeScript)
• DataLake Storage-testcases

Bijdragen

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