Share via

Biblioteca cliente de Azure Storage File Data Lake para JavaScript: versión 12.17.0

  • Artículo

Azure Data Lake Storage (ADLS) incluye todas las funcionalidades necesarias para facilitar a los desarrolladores, científicos de datos y analistas almacenar datos de cualquier tamaño, forma y velocidad, y realizar todos los tipos de procesamiento y análisis en plataformas e idiomas. Quita las complejidades de ingesta y almacenamiento de todos los datos acelerando al mismo tiempo la puesta en marcha y ejecución con análisis de lotes, streaming e interactivos.

Este proyecto proporciona una biblioteca cliente en JavaScript que facilita el consumo de Microsoft Azure Storage servicio Data Lake.

Use las bibliotecas cliente de este paquete para:

  • sistemas de archivos Create/List/Delete
  • Create/Read/List/Update/Delete Rutas de acceso, directorios y archivos

vínculos clave:

Introducción

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Instalar el paquete

La manera preferida de instalar la biblioteca cliente de Azure Storage Data Lake para JavaScript es usar el administrador de paquetes npm. Escriba lo siguiente en una ventana de terminal:

npm install @azure/storage-file-datalake

Autenticar el cliente

Azure Storage admite varias maneras de autenticarse. Para interactuar con el servicio Azure Data Lake Storage, deberá crear una instancia de un cliente de Storage: DataLakeServiceClient, DataLakeFileSystemCliento DataLakePathClient por ejemplo. Consulte ejemplos para crear para obtener más información sobre la DataLakeServiceClient autenticación.

Azure Active Directory

El servicio Azure Data Lake Storage admite el uso de Azure Active Directory para autenticar las solicitudes en sus API. El paquete @azure/identity proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. Consulte el archivo Léame para @azure/identity obtener más detalles y ejemplos para empezar.

Compatibilidad

Esta biblioteca es compatible con Node.js y exploradores, y se valida con las versiones de ltS Node.js (>=8.16.0) y las versiones más recientes de Chrome, Firefox y Edge.

Trabajos web

Esta biblioteca requiere que determinados objetos DOM estén disponibles globalmente cuando se usan en el explorador, que los trabajadores web no están disponibles de forma predeterminada. Tendrá que polirrellenar estos elementos para que esta biblioteca funcione en trabajos web.

Para más información, consulte nuestra documentación sobre el uso del SDK de Azure para JS en trabajos web.

Esta biblioteca depende de las siguientes API DOM que necesitan polirrellenes externos cargados cuando se usan en trabajos web:

Diferencias entre Node.js y exploradores

Hay diferencias entre Node.js y el entorno de ejecución de exploradores. Al empezar a trabajar con esta biblioteca, preste atención a las API o clases marcadas con "ONLY AVAILABLE IN NODE.JS RUNTIME" o "ONLY AVAILABLE IN BROWSER" (SOLO DISPONIBLE EN EXPLORADORES).

  • Si un archivo contiene datos comprimidos en gzip formato o deflate y su codificación de contenido se establece en consecuencia, el comportamiento de descarga es diferente entre Node.js y exploradores. En Node.js los clientes de almacenamiento descargarán el archivo en su formato comprimido, mientras que en los exploradores los datos se descargarán en formato des comprimido.
Características, interfaces, clases o funciones solo disponibles en Node.js
  • Autorización de clave compartida basada en el nombre de cuenta y la clave de cuenta
    • StorageSharedKeyCredential
  • Generación de firmas de acceso compartido (SAS)
    • generateAccountSASQueryParameters()
    • generateDataLakeSASQueryParameters()
  • Carga y descarga en paralelo. Tenga en cuenta que DataLakeFileClient.upload() está disponible tanto en Node.js como en exploradores.
    • DataLakeFileClient.uploadFile()
    • DataLakeFileClient.uploadStream()
    • DataLakeFileClient.readToBuffer()
    • DataLakeFileClient.readToFile()
Características, interfaces, clases o funciones solo disponibles en exploradores
  • N/D

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.

CORS

Debe configurar reglas de uso compartido de recursos entre orígenes (CORS) para la cuenta de almacenamiento si necesita desarrollar para exploradores. Vaya a Azure Portal y Explorador de Azure Storage, busque la cuenta de almacenamiento, cree nuevas reglas de CORS para blob/queue/file/table service(s).

Por ejemplo, puede crear la siguiente configuración de CORS para la depuración. Pero personalice cuidadosamente la configuración según sus requisitos en el entorno de producción.

  • Orígenes permitidos: *
  • Verbos permitidos: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Encabezados permitidos: *
  • Encabezados expuestos: *
  • Antigüedad máxima (segundos): 86400

Aviso: Data Lake actualmente comparte la configuración de CORS para blob service.

Conceptos clave

Azure Data Lake Storage Gen2 se diseñó para:

  • Servir varios petabytes de información al tiempo que mantiene cientos de gigabits de rendimiento
  • Le permite administrar fácilmente grandes cantidades de datos.

Entre las características clave de DataLake Storage Gen2 se incluyen:

  • Acceso compatible con Hadoop
  • Un superconjunto de permisos POSIX
  • Rentable en términos de capacidad de almacenamiento y transacciones de bajo costo
  • Controlador optimizado para el análisis de macrodatos

Parte fundamental de Data Lake Storage Gen2 es la incorporación de un espacio de nombres jerárquico en Blob Storage. El espacio de nombres jerárquico organiza los objetos o archivos en una jerarquía de directorios para un acceso eficaz a los datos.

Anteriormente, los análisis basados en la nube tenían que llegar a un acuerdo en materia de rendimiento, administración y seguridad. Data Lake Storage Gen2 aborda cada uno de estos aspectos de las siguientes formas:

  • El rendimiento se optimiza porque no es necesario copiar ni transformar datos como requisito previo para el análisis. El espacio de nombres jerárquico mejora considerablemente el rendimiento de las operaciones de administración de directorios y, consecuentemente, el rendimiento general del trabajo.
  • La administración es más fácil, ya que puede organizar y manipular archivos a través de directorios y subdirectorios.
  • La seguridad se aplicable porque se pueden definir permisos POSIX en los directorios o archivos individuales.
  • La rentabilidad se hace posible gracias a que Data Lake Storage Gen2 se ha diseñado a partir de Azure Blob Storage de bajo costo. Las características adicionales reducen aún más el costo total de propiedad para la ejecución de análisis de macrodatos en Azure.

Data Lake Storage ofrece tres tipos de recursos:

  • La cuenta de almacenamiento usada a través de DataLakeServiceClient
  • Un sistema de archivos de la cuenta de almacenamiento que se usa a través de DataLakeFileSystemClient
  • Ruta de acceso de un sistema de archivos que se usa a través DataLakeDirectoryClient de o DataLakeFileClient
Azure DataLake Gen2 Blob
Sistema de archivos Contenedor
Ruta de acceso (archivo o directorio) Blob

Nota: Esta biblioteca cliente solo admite cuentas de almacenamiento con espacio de nombres jerárquico (HNS) habilitado.

Ejemplos

Importación del paquete

Para usar los clientes, importe el paquete en el archivo:

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

Como alternativa, importe de forma selectiva solo los tipos que necesita:

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

Create el cliente del servicio Data Lake

DataLakeServiceClient requiere una dirección URL para el servicio data lake y una credencial de acceso. También acepta algunas opciones de configuración en el options parámetro .

con DefaultAzureCredential desde @azure/identity el paquete

Forma recomendada de crear una instancia de un DataLakeServiceClient

Notificaciones. Azure Data Lake reutiliza actualmente roles relacionados con blobs como "Propietario de datos de blobs de almacenamiento" durante la siguiente autenticación de OAuth de AAD.

Configuración: Referencia: autorización del acceso a blobs (data lake) y colas con Azure Active Directory desde una aplicación cliente: /azure/storage/common/storage-auth-aad-app

  • Registre una nueva aplicación de AAD y conceda permisos para acceder a Azure Storage en nombre del usuario que ha iniciado sesión.

    • Registro de una nueva aplicación en Azure Active Directory (en azure-portal): /azure/active-directory/develop/quickstart-register-app
    • En la API permissions sección, seleccione Add a permission y elija Microsoft APIs.
    • Seleccione Azure Storage y active la casilla situada junto a y, a user_impersonation continuación, haga clic en Add permissions. Esto permitiría que la aplicación acceda a Azure Storage en nombre del usuario que ha iniciado sesión.

  • Concesión de acceso a datos de Azure Data Lake con RBAC en Azure Portal

    • Roles de RBAC para blobs (data lake) y colas: /azure/storage/common/storage-auth-aad-rbac-portal.
    • En Azure Portal, vaya a la cuenta de almacenamiento y asigne el rol Colaborador de datos de Storage Blob a la aplicación de AAD registrada desde Access control (IAM) la pestaña (en la barra de navegación del lado izquierdo de la cuenta de almacenamiento en Azure-Portal).

  • Configuración del entorno para el ejemplo

    • En la página de información general de la aplicación de AAD, anote y CLIENT IDTENANT ID. En la pestaña "Certificados & secretos", cree un secreto y anotelo.
    • Asegúrese de que tiene AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET como variables de entorno para ejecutar correctamente el ejemplo(Puede aprovechar 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
);

Consulte el ejemplo de autenticación de Azure AD para obtener un ejemplo completo con este método.

[Nota: los pasos anteriores solo son para Node.js]

uso de cadena de conexión

Como alternativa, puede crear una DataLakeServiceClient instancia de mediante el fromConnectionString() método estático con el cadena de conexión completo como argumento. (El cadena de conexión se puede obtener en Azure Portal). [SOLO DISPONIBLE EN NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

Con StorageSharedKeyCredential

Como alternativa, cree una instancia DataLakeServiceClient de con un StorageSharedKeyCredential mediante el paso de account-name y account-key como argumentos. (El nombre de cuenta y la clave de cuenta se pueden obtener en Azure Portal). [SOLO DISPONIBLE EN 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
);

con token de SAS

Además, puede crear DataLakeServiceClient una instancia de con una firma de acceso compartido (SAS). Puede obtener el token de SAS desde Azure Portal o generar uno mediante 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}`
);

Create un nuevo sistema de archivos

Use DataLakeServiceClient.getFileSystemClient() para obtener una instancia de cliente del sistema de archivos y, a continuación, cree un nuevo recurso de sistema de archivos.

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

Enumeración de los sistemas de archivos

Use DataLakeServiceClient.listFileSystems() la función para iterar los sistemas de archivos, con la nueva for-await-of sintaxis:

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

Como alternativa, sin usar 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();

Además, la paginación también se admite para enumerar a través de 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();

Create y eliminar un directorio

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

Creación de un archivo

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

Enumerar rutas de acceso dentro de un sistema de archivos

Similar a enumerar sistemas de archivos.

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

Descargar un archivo y convertirlo en una cadena (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();

Descargar un archivo y convertirlo en una cadena (exploradores)

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

Solución de problemas

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

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

setLogLevel("info");

Pasos siguientes

Más ejemplos de código:

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones