Bibliothèque de client Azure Storage File Data Lake pour JavaScript - version 12.25.0

Article
11/20/2024

Azure Data Lake Storage (ADLS) inclut toutes les fonctionnalités requises pour faciliter les développeurs, les scientifiques des données et les analystes de stocker des données de toute taille, forme et vitesse, et effectuer tous les types de traitement et d’analytique sur les plateformes et les langages. Il supprime la complexité de l’ingestion et du stockage de toutes vos données tout en le rendant plus rapide pour être opérationnel avec des analyses par lots, en streaming et interactives.

Ce projet fournit une bibliothèque cliente en JavaScript qui facilite l’utilisation du service Microsoft Azure Storage Data Lake.

Utilisez les bibliothèques clientes dans ce package pour :

Créer/répertorier/supprimer des systèmes de fichiers
Créer/lire/liste/mettre à jour/supprimer des chemins, des répertoires et des fichiers

liens clés :

Commencer

Environnements actuellement pris en charge

versions LTS de Node.js
Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre de stratégie de support .

Conditions préalables

Un abonnement Azure
Un compte de stockage

Installer le package

La méthode recommandée pour installer la bibliothèque cliente Azure Storage Data Lake pour JavaScript consiste à utiliser le gestionnaire de package npm. Tapez ce qui suit dans une fenêtre de terminal :

npm install @azure/storage-file-datalake

Authentifier le client

Stockage Azure prend en charge plusieurs façons de s’authentifier. Pour interagir avec le service Azure Data Lake Storage, vous devez créer une instance d’un client de stockage , DataLakeServiceClient, DataLakeFileSystemClientou DataLakePathClient par exemple. Consultez exemples pour créer le DataLakeServiceClient pour en savoir plus sur l’authentification.

Azure Active Directory
de clé partagée
signatures d’accès partagé

Azure Active Directory

Le service Azure Data Lake Storage prend en charge l’utilisation d’Azure Active Directory pour authentifier les demandes auprès de ses API. Le package @azure/identity fournit divers types d’informations d’identification que votre application peut utiliser pour ce faire. Pour plus d’informations et d’exemples, consultez le README pour @azure/identity pour commencer.

Compatibilité

Cette bibliothèque est compatible avec Node.js et les navigateurs, et validée par rapport aux versions de LTS Node.js (>=8.16.0) et les dernières versions de Chrome, Firefox et Edge.

Web Workers

Cette bibliothèque nécessite que certains objets DOM soient globalement disponibles lorsqu’ils sont utilisés dans le navigateur, que les travailleurs web ne rendent pas disponibles par défaut. Vous devrez les polyfiller pour que cette bibliothèque fonctionne dans les workers web.

Pour plus d’informations, reportez-vous à notre documentation pour l’utilisation du Kit de développement logiciel (SDK) Azure pour JS dans web Workers

Cette bibliothèque dépend des API DOM suivantes qui nécessitent des polyfills externes chargés lors de l’utilisation dans les workers web :

Différences entre les Node.js et les navigateurs

Il existe des différences entre Node.js et le runtime des navigateurs. Lors de la prise en main de cette bibliothèque, faites attention aux API ou aux classes marquées avec « DISPONIBLE UNIQUEMENT DANS NODE.JS RUNTIME » ou « UNIQUEMENT DISPONIBLE DANS LES NAVIGATEURS ».

Si un fichier contient des données compressées au format gzip ou deflate et que son encodage de contenu est défini en conséquence, le comportement de téléchargement est différent entre Node.js et les navigateurs. Dans Node.js clients de stockage téléchargent le fichier dans son format compressé, tandis que dans les navigateurs, les données seront téléchargées au format décompressé.

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans Node.js

Autorisation de clé partagée basée sur le nom du compte et la clé de compte
- StorageSharedKeyCredential
Génération de signature d’accès partagé (SAP)
- generateAccountSASQueryParameters()
- generateDataLakeSASQueryParameters()
Chargement et téléchargement parallèles. Notez que DataLakeFileClient.upload() est disponible dans les Node.js et les navigateurs.
- DataLakeFileClient.uploadFile()
- DataLakeFileClient.uploadStream()
- DataLakeFileClient.readToBuffer()
- DataLakeFileClient.readToFile()

Fonctionnalités, interfaces, classes ou fonctions uniquement disponibles dans les navigateurs

JavaScript Bundle

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

CORS

Vous devez configurer règles de partage de ressources cross-origin (CORS) pour votre compte de stockage si vous devez développer pour les navigateurs. Accédez au portail Azure et à l’Explorateur Stockage Azure, recherchez votre compte de stockage, créez de nouvelles règles CORS pour les services blob/file/file/table.

Par exemple, vous pouvez créer les paramètres CORS suivants pour le débogage. Mais personnalisez soigneusement les paramètres en fonction de vos besoins dans l’environnement de production.

Origines autorisées : *
Verbes autorisés : DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
En-têtes autorisés : *
En-têtes exposés : *
Âge maximal (secondes) : 86400

Remarque : Data Lake partage actuellement les paramètres CORS pour le service d’objets blob.

Concepts clés

Azure Data Lake Storage Gen2 a été conçu pour :

Servir plusieurs pétaoctets d’informations tout en conservant des centaines de gigaoctets de débit
Vous permettre de gérer facilement des quantités massives de données

Les principales fonctionnalités de DataLake Storage Gen2 sont les suivantes :

Accès compatible Hadoop
Un super ensemble d’autorisations POSIX
Économique en termes de capacité de stockage et de transactions à faible coût
Pilote optimisé pour l’analytique Big Data

Une partie fondamentale de Data Lake Storage Gen2 est l’ajout d’un espace de noms hiérarchique au stockage Blob. L’espace de noms hiérarchique organise les objets/fichiers dans une hiérarchie de répertoires pour un accès efficace aux données.

Dans le passé, l’analytique basée sur le cloud a dû compromettre les performances, la gestion et la sécurité. Data Lake Storage Gen2 traite chacun de ces aspects de la manière suivante :

Les performances sont optimisées, car vous n’avez pas besoin de copier ou de transformer des données en tant que prérequis pour l’analyse. L’espace de noms hiérarchique améliore considérablement les performances des opérations de gestion d’annuaire, ce qui améliore les performances globales du travail.
La gestion est plus facile, car vous pouvez organiser et manipuler des fichiers via des répertoires et des sous-répertoires.
La sécurité est appliquée, car vous pouvez définir des autorisations POSIX sur des répertoires ou des fichiers individuels.
L’efficacité des coûts est rendue possible, car Data Lake Storage Gen2 repose sur le stockage Blob Azure à faible coût. Les fonctionnalités supplémentaires réduisent davantage le coût total de possession pour l’exécution de l’analytique Big Data sur Azure.

Data Lake Storage offre trois types de ressources :

Le compte de stockage utilisé via DataLakeServiceClient
Un système de fichiers dans le compte de stockage utilisé via DataLakeFileSystemClient
Un chemin d’accès dans un système de fichiers utilisé via DataLakeDirectoryClient ou DataLakeFileClient

Azure DataLake Gen2	BLOB
Système de fichiers	Conteneur
Chemin d’accès (fichier ou répertoire)	BLOB

Remarque : cette bibliothèque cliente prend uniquement en charge les comptes de stockage avec l’espace de noms hiérarchique (HNS) activé.

Exemples

Importer le package
Créer le client data lake service
Créer un système de fichiers
Répertorier les systèmes de fichiers
Créer et supprimer un répertoire
Créer un fichier
Répertorier les chemins d’accès à l’intérieur d’un système de fichiers
Télécharger un fichier et le convertir en chaîne (Node.js)
Télécharger un fichier et le convertir en chaîne (navigateurs)

Importer le package

Pour utiliser les clients, importez le package dans votre fichier :

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

Vous pouvez également importer sélectivement uniquement les types dont vous avez besoin :

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

Créer le client de service data lake

Le DataLakeServiceClient nécessite une URL vers le service data lake et des informations d’identification d’accès. Il accepte également certains paramètres dans le paramètre options.

avec `DefaultAzureCredential` à partir du package de `@azure/identity`

Méthode recommandée pour instancier un DataLakeServiceClient

Remarquer. Azure Data Lake réutilise actuellement des rôles liés aux objets blob tels que « Propriétaire des données blob de stockage » lors de l’authentification OAuth AAD.

Configuration : Référence - Autoriser l’accès aux objets blob (data lake) et aux files d’attente avec Azure Active Directory à partir d’une application cliente - /azure/storage/common/storage-auth-aad-app

Inscrivez une nouvelle application AAD et accordez des autorisations pour accéder au stockage Azure au nom de l’utilisateur connecté.
- Inscrire une nouvelle application dans Azure Active Directory(dans le portail Azure) - /azure/active-directory/develop/quickstart-register-app
- Dans la section API permissions, sélectionnez Add a permission et choisissez Microsoft APIs.
- Sélectionnez Azure Storage et cochez la case en regard de user_impersonation, puis cliquez sur Add permissions. Cela permettrait à l’application d’accéder au stockage Azure pour le compte de l’utilisateur connecté.
Accorder l’accès aux données Azure Data Lake avec RBAC dans le portail Azure
- Rôles RBAC pour les objets blob (data lake) et les files d’attente - /azure/storage/common/storage-auth-aad-rbac-portal.
- Dans le portail Azure, accédez à votre compte de stockage et attribuez rôle Contributeur aux données blob de stockage au rôle AAD inscrit à partir de l’onglet Access control (IAM) (dans la barre de navigation de gauche de votre compte de stockage dans le portail Azure).
Configuration de l’environnement pour l’exemple
- Dans la page vue d’ensemble de votre application AAD, notez les CLIENT ID et les TENANT ID. Sous l’onglet « Certificats & secrets », créez un secret et notez-le.
- Vérifiez que vous avez AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET en tant que variables d’environnement pour exécuter correctement l’exemple (Peut tirer parti de 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
);

Consultez l’exemple 'authentification Azure AD pour obtenir un exemple complet à l’aide de cette méthode.

[Remarque - Les étapes ci-dessus ne concernent que Node.js]

à l’aide de la chaîne de connexion

Vous pouvez également instancier un DataLakeServiceClient à l’aide de la méthode statique fromConnectionString() avec la chaîne de connexion complète comme argument. (La chaîne de connexion peut être obtenue à partir du portail Azure.) [DISPONIBLE UNIQUEMENT DANS NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

avec `StorageSharedKeyCredential`

Vous pouvez également instancier un DataLakeServiceClient avec un StorageSharedKeyCredential en passant le nom du compte et la clé de compte en tant qu’arguments. (Le nom du compte et la clé de compte peuvent être obtenus à partir du portail Azure.) [DISPONIBLE UNIQUEMENT DANS 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
);

avec un jeton SAP

En outre, vous pouvez instancier un DataLakeServiceClient avec des signatures d’accès partagé (SAP). Vous pouvez obtenir le jeton SAP à partir du portail Azure ou en générer un à l’aide de 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}`
);

Créer un système de fichiers

Utilisez DataLakeServiceClient.getFileSystemClient() pour obtenir une instance cliente du système de fichiers, puis créez une ressource de système de fichiers.

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

Répertorier les systèmes de fichiers

Utilisez DataLakeServiceClient.listFileSystems() fonction pour itérer les systèmes de fichiers, avec la nouvelle syntaxe 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 fileSystems = datalakeServiceClient.listFileSystems();
  for await (const fileSystem of fileSystems) {
    console.log(`File system ${i++}: ${fileSystem.name}`);
  }
}

main();

Sinon, sans utiliser 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();

En outre, la pagination est prise en charge pour la description trop 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();

Créer et supprimer un répertoire

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

Créer un fichier

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

Répertorier les chemins d’accès à l’intérieur d’un système de fichiers

Similaire à la liste des systèmes de fichiers.

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

Téléchargez un fichier et convertissez-le en chaîne (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();

Téléchargez un fichier et convertissez-le en chaîne (Navigateurs)

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

Dépannage

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Étapes suivantes

Autres exemples de code :

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions

Partager via

Bibliothèque de client Azure Storage File Data Lake pour JavaScript - version 12.25.0

Commencer

Environnements actuellement pris en charge

Conditions préalables

Installer le package

Authentifier le client

Azure Active Directory

Compatibilité

Web Workers

Différences entre les Node.js et les navigateurs

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans Node.js

Fonctionnalités, interfaces, classes ou fonctions uniquement disponibles dans les navigateurs

JavaScript Bundle

CORS

Concepts clés

Exemples

Importer le package

Créer le client de service data lake

avec `DefaultAzureCredential` à partir du package de `@azure/identity`

à l’aide de la chaîne de connexion

avec `StorageSharedKeyCredential`

avec un jeton SAP

Créer un système de fichiers

Répertorier les systèmes de fichiers

Créer et supprimer un répertoire

Créer un fichier

Répertorier les chemins d’accès à l’intérieur d’un système de fichiers

Téléchargez un fichier et convertissez-le en chaîne (Node.js)

Téléchargez un fichier et convertissez-le en chaîne (Navigateurs)

Dépannage

Étapes suivantes

Contribuant

Ressources supplémentaires

Partager via

Bibliothèque de client Azure Storage File Data Lake pour JavaScript - version 12.25.0

Commencer

Environnements actuellement pris en charge

Conditions préalables

Installer le package

Authentifier le client

Azure Active Directory

Compatibilité

Web Workers

Différences entre les Node.js et les navigateurs

Fonctionnalités, interfaces, classes ou fonctions disponibles uniquement dans Node.js

Fonctionnalités, interfaces, classes ou fonctions uniquement disponibles dans les navigateurs

JavaScript Bundle

CORS

Concepts clés

Exemples

Importer le package

Créer le client de service data lake

avec DefaultAzureCredential à partir du package de @azure/identity

à l’aide de la chaîne de connexion

avec StorageSharedKeyCredential

avec un jeton SAP

Créer un système de fichiers

Répertorier les systèmes de fichiers

Créer et supprimer un répertoire

Créer un fichier

Répertorier les chemins d’accès à l’intérieur d’un système de fichiers

Téléchargez un fichier et convertissez-le en chaîne (Node.js)

Téléchargez un fichier et convertissez-le en chaîne (Navigateurs)

Dépannage

Étapes suivantes

Contribuant

Ressources supplémentaires

avec `DefaultAzureCredential` à partir du package de `@azure/identity`

avec `StorageSharedKeyCredential`