Клиентская библиотека озера файловых данных службы хранилища Azure для JavaScript — версия 12.27.0

Azure Data Lake Storage (ADLS) включает все возможности, необходимые для разработчиков, специалистов по обработке и анализу данных и аналитиков для хранения данных любого размера, фигуры и скорости, а также для всех типов обработки и аналитики на разных платформах и языках. При этом удаляются сложности приема и хранения всех данных, что позволяет быстрее получать и работать с пакетной, потоковой и интерактивной аналитикой.

Этот проект предоставляет клиентскую библиотеку в JavaScript, которая упрощает использование службы Data Lake службы хранилища Microsoft Azure.

Используйте клиентские библиотеки в этом пакете, чтобы:

• Создание и удаление файловой системы
• Create/Read/List/Update/Delete Paths, Directoryies and Files

key links:

• Source code
• Package (npm)
• Справочная документация по API
• Product documentation
• Samples
• REST API Озера данных службы хранилища Azure

Getting started

Поддерживаемые в настоящее время среды

• версии LTS Node.js
• Последние версии Safari, Chrome, Edge и Firefox.

See our support policy for more details.

Prerequisites

• An Azure subscription
• A Storage Account

Установка пакета

Предпочтительный способ установки клиентской библиотеки Data Lake службы хранилища Azure для JavaScript — использовать диспетчер пакетов npm. Введите следующее в окно терминала:

npm install @azure/storage-file-datalake

Проверка подлинности клиента

Служба хранилища Azure поддерживает несколько способов проверки подлинности. Чтобы взаимодействовать со службой Azure Data Lake Storage, необходимо создать экземпляр клиента хранилища — DataLakeServiceClient, DataLakeFileSystemClientили DataLakePathClient. Дополнительные сведения о проверке подлинности см. в примерах для создания DataLakeServiceClient.

• Azure Active Directory
• Shared Key
• подписей общего доступа

Azure Active Directory

Служба Azure Data Lake Storage поддерживает использование Azure Active Directory для проверки подлинности запросов к своим API. Пакет @azure/identity предоставляет различные типы учетных данных, которые приложение может использовать для этого. Чтобы приступить к работе, ознакомьтесь с README для @azure/identity получения дополнительных сведений и примеров.

Compatibility

Эта библиотека совместима с Node.js и браузерами и проверена на основе версий LTS Node.js (>=8.16.0) и последних версий Chrome, Firefox и Edge.

Web Workers

Эта библиотека требует, чтобы некоторые объекты DOM были глобально доступны при использовании в браузере, которые веб-работники по умолчанию не делают доступными. Эти библиотеки необходимо заполнить, чтобы эта библиотека работала в веб-рабочих нагрузках.

Дополнительные сведения см. в нашей документации по использованию пакета SDK Azure для JS в веб-рабочих

Эта библиотека зависит от следующих API-интерфейсов DOM, которые нуждаются во внешних полизаполнениях, загруженных при использовании в веб-рабочих нагрузках:

• document
• DOMParser
• Node
• XMLSerializer

Различия между Node.js и браузерами

Существуют различия между средой выполнения Node.js и браузерами. При начале работы с этой библиотекой обратите внимание на API-интерфейсы или классы, помеченные "ТОЛЬКО ДОСТУПНО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS" или "ТОЛЬКО ДОСТУПНЫ В БРАУЗЕРАХ".

• Если файл содержит сжатые данные в gzip или deflate формате, а его кодировка содержимого задана соответствующим образом, то поведение загрузки отличается от Node.js и браузеров. В Node.js клиенты хранилища скачивают файл в сжатом формате, а в браузерах данные будут скачаны в не сжатый формат.

Функции, интерфейсы, классы или функции, доступные только в Node.js

• Авторизация общего ключа на основе имени учетной записи и ключа учетной записи
  • StorageSharedKeyCredential
• Создание подписанного URL-адреса (SAS)
  • generateAccountSASQueryParameters()
  • generateDataLakeSASQueryParameters()
• Параллельная отправка и скачивание. Обратите внимание, что DataLakeFileClient.upload() доступна как в Node.js, так и в браузерах.
  • DataLakeFileClient.uploadFile()
  • DataLakeFileClient.uploadStream()
  • DataLakeFileClient.readToBuffer()
  • DataLakeFileClient.readToFile()

Функции, интерфейсы, классы или функции, доступные только в браузерах

• N/A

JavaScript Bundle

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. For details on how to do this, please refer to our bundling documentation.

CORS

Необходимо настроить правила совместного использования ресурсов (CORS) для учетной записи хранения, если необходимо разработать для браузеров. Перейдите на портал Azure и обозреватель службы хранилища Azure, найдите свою учетную запись хранения, создайте новые правила CORS для больших двоичных объектов, очередей, файлов и таблиц.

Например, можно создать следующие параметры CORS для отладки. Но настройте параметры тщательно в соответствии с вашими требованиями в рабочей среде.

• Допустимые источники: *
• Разрешенные команды: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Разрешенные заголовки: *
• Открытые заголовки: *
• Максимальный возраст (в секундах): 86400

Обратите внимание: Data Lake в настоящее время предоставляет общие параметры CORS для службы BLOB-объектов.

Key concepts

Azure Data Lake Storage 2-го поколения был разработан для:

• Обслуживание нескольких петабайтов информации при поддержании сотен гигабит пропускной способности
• Позволяет легко управлять большими объемами данных

К ключевым функциям хранилища DataLake 2-го поколения относятся:

• Совместимый доступ к Hadoop
• Супер набор разрешений POSIX
• Экономичность с точки зрения емкости и транзакций хранилища с низкими затратами
• Оптимизированный драйвер для аналитики больших данных

Основной частью Data Lake Storage 2-го поколения является добавление иерархического пространства имен в хранилище BLOB-объектов. Иерархическое пространство имен упорядочивает объекты и файлы в иерархию каталогов для эффективного доступа к данным.

В прошлом облачная аналитика должна была скомпрометироваться в областях производительности, управления и безопасности. Data Lake Storage 2-го поколения обращается к каждому из этих аспектов следующим образом:

• Производительность оптимизирована, так как для анализа не требуется копировать или преобразовывать данные. Иерархическое пространство имен значительно повышает производительность операций управления каталогами, что повышает общую производительность задания.
• Управление проще, так как вы можете упорядочивать файлы и управлять ими с помощью каталогов и подкаталогов.
• Безопасность применяется, так как можно определить разрешения POSIX для каталогов или отдельных файлов.
• Эффективность затрат становится возможной, так как Data Lake Storage 2-го поколения построен на основе низкой стоимости хранилища BLOB-объектов Azure. Дополнительные функции еще больше снижают общую стоимость владения для выполнения аналитики больших данных в Azure.

Data Lake Storage предлагает три типа ресурсов:

• The storage account used via DataLakeServiceClient
• A file system in the storage account used via DataLakeFileSystemClient
• A path in a file system used via DataLakeDirectoryClient or DataLakeFileClient

Примечание. Эта клиентская библиотека поддерживает только учетные записи хранения с включенным иерархическим пространством имен (HNS).

Examples

• Импорт пакета
• Создание клиента службы озера данных
• Создание новой файловой системы
• Перечисление файловой системы
• Создание и удаление каталога
• создание файла
• пути списка в файловой системе
• Скачайте файл и преобразуйте его в строку (Node.js)
• Скачайте файл и преобразуйте его в строку (браузеры)

Импорт пакета

Чтобы использовать клиенты, импортируйте пакет в файл:

import * as AzureStorageDataLake from "@azure/storage-file-datalake";

Кроме того, выборочно импортируйте только необходимые типы:

import { DataLakeServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-datalake";

Создание клиента службы озера данных

Для DataLakeServiceClient требуется URL-адрес службы озера данных и учетные данные доступа. Он также при необходимости принимает некоторые параметры в параметре options.

с DefaultAzureCredential из пакета @azure/identity

Рекомендуемый способ создания экземпляра DataLakeServiceClient

Notice. Azure Data Lake в настоящее время повторно использует связанные с BLOB-объектами роли, такие как "Владелец данных BLOB-объектов хранилища" после проверки подлинности OAuth AAD.

Настройка: Справочник — авторизация доступа к большим двоичным объектам (озеру данных) и очередям с помощью Azure Active Directory из клиентского приложения — https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

• Зарегистрируйте новое приложение AAD и предоставьте разрешения на доступ к службе хранилища Azure от имени вошедшего пользователя.

  • Зарегистрируйте новое приложение в Azure Active Directory(в azure-portal) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
  • В разделе API permissions выберите Add a permission и выберите Microsoft APIs.
  • Выберите Azure Storage и установите флажок рядом с user_impersonation и щелкните Add permissions. Это позволит приложению получить доступ к службе хранилища Azure от имени вошедшего пользователя.

• Предоставление доступа к данным Azure Data Lake с помощью RBAC на портале Azure

  • Роли RBAC для больших двоичных объектов (озеро данных) и очередей — https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
  • На портале Azure перейдите к учетной записи хранения и назначьте участнику данных BLOB-объектов хранилища роль зарегистрированного приложения AAD на вкладке Access control (IAM) (на левой панели навигации учетной записи хранения на портале Azure).

• Настройка среды для примера

  • На странице обзора приложения AAD запишите CLIENT ID и TENANT ID. На вкладке "Сертификаты & секреты" создайте секрет и запишите это вниз.
  • Убедитесь, что у вас есть AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET в качестве переменных среды для успешного выполнения примера (может использовать process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { DataLakeServiceClient } from "@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,
);

Полный пример проверки подлинности Azure AD см. в примера проверки подлинности Azure AD.

[Примечание. Приведенные выше шаги предназначены только для Node.js]

использование строки подключения

Кроме того, можно создать экземпляр DataLakeServiceClient с помощью статического метода fromConnectionString() с полной строкой подключения в качестве аргумента. (Строка подключения может быть получена на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

с StorageSharedKeyCredential

Кроме того, вы создаете экземпляр DataLakeServiceClient с StorageSharedKeyCredential путем передачи имени учетной записи и ключа учетной записи в качестве аргументов. (Имя учетной записи и ключ учетной записи можно получить на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

import { StorageSharedKeyCredential, DataLakeServiceClient } from "@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,
);

с маркером SAS

Кроме того, можно создать экземпляр DataLakeServiceClient с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure или создать его с помощью generateAccountSASQueryParameters().

import { DataLakeServiceClient } from "@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}`,
);

Создание файловой системы

Используйте DataLakeServiceClient.getFileSystemClient() для получения экземпляра клиента файловой системы, а затем создайте новый ресурс файловой системы.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

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

Перечисление файловой системы

Используйте функцию DataLakeServiceClient.listFileSystems() для итерации файловой системы с новым синтаксисом for-await-of:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
for await (const fileSystem of fileSystems) {
  console.log(`File system ${i++}: ${fileSystem.name}`);
}

Кроме того, без использования for-await-of:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
let { value, done } = await fileSystems.next();
while (!done) {
  console.log(`File system ${i++}: ${value.name}`);
  ({ value, done } = await fileSystems.next());
}

Кроме того, для перечисления также поддерживается разбиение на страницы с помощью byPage():

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

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}`);
    }
  }
}

Создание и удаление каталога

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const directoryClient = fileSystemClient.getDirectoryClient("directory");
await directoryClient.create();
await directoryClient.delete();

Создание файла

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

const content = "Hello world!";
const fileName = `newfile${+new Date()}`;
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`);

Вывод списка путей в файловой системе

Аналогично перечислению файловой системы.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
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}`);
}

Скачайте файл и преобразуйте его в строку (Node.js)

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
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();
if (downloadResponse.readableStreamBody) {
  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: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

Скачайте файл и преобразуйте его в строку (браузеры)

import { DataLakeServiceClient } from "@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>";
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();
if (downloadResponse.contentAsBlob) {
  const blob = await downloadResponse.contentAsBlob;
  const downloaded = await blob.text();
  console.log(`Downloaded file content ${downloaded}`);
}

Troubleshooting

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Next steps

Дополнительные примеры кода:

• Примеры хранилища DataLake (JavaScript)
• Примеры хранилища DataLake (TypeScript)
• тестовые случаи хранения DataLake

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.