Клиентская библиотека Озера данных хранилища Azure для JavaScript версии 12.25.0

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

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

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

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

ключевые ссылки:

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

Начало работы

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

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

Дополнительные сведения см. в политике поддержки .

Необходимые условия

• подписки Azure
• учетной записи хранения

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

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

npm install @azure/storage-file-datalake

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

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

• Azure Active Directory
• общий ключ
• подписей общего доступа

Azure Active Directory

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

Совместимость

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

Веб-рабочие роли

Эта библиотека требует, чтобы некоторые объекты 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

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

CORS

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

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

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

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

Основные понятия

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 предлагает три типа ресурсов:

• Учетная запись хранения , используемая с помощью DataLakeServiceClient
• файловой системы в учетной записи хранения, используемой DataLakeFileSystemClient
• Путь в файловой системе, используемый или

Azure DataLake 2-го поколения	Капля
Файловая система	Контейнер
Путь (файл или каталог)	Капля

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

Примеры

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Регистрация нового приложения в Azure Active Directory (на портале Azure) — /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 для больших двоичных объектов (озера данных) и очередей — /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).

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

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

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

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

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

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

с StorageSharedKeyCredential

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

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

с маркером SAS

Кроме того, можно создать экземпляр DataLakeServiceClient с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure или создать его с помощью 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}`
);

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

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

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

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

Используйте функцию DataLakeServiceClient.listFileSystems() для итерации файловой системы с новым синтаксисом 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();

Кроме того, без использования 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();

Кроме того, для перечисления также поддерживается разбиение на страницы с помощью 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();

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

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

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

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

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

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

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

Скачайте файл и преобразуйте его в строку (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();

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

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

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

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

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

setLogLevel("info");

Дальнейшие действия

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

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

Способствует

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.