JavaScript 用の Azure Storage File Data Lake クライアント ライブラリ - バージョン 12.27.0

Azure Data Lake Storage (ADLS) には、開発者、データ サイエンティスト、アナリストが任意のサイズ、形状、速度のデータを簡単に格納し、プラットフォームと言語全体であらゆる種類の処理と分析を行うために必要なすべての機能が含まれています。 これにより、すべてのデータの取り込みと格納の複雑さが排除され、バッチ分析、ストリーミング分析、対話型分析を使用して迅速に稼働できるようになります。

このプロジェクトは、Microsoft Azure Storage Data Lake サービスを簡単に使用できる JavaScript のクライアント ライブラリを提供します。

このパッケージのクライアント ライブラリを使用して、次の操作を行います。

• ファイル システムの作成/一覧表示/削除
• パス、ディレクトリ、ファイルの作成/読み取り/一覧表示/更新/削除

key links:

• Source code
• Package (npm)
• API リファレンス ドキュメント
• Product documentation
• Samples
• Azure Storage Data Lake REST API を する

Getting started

現在サポートされている環境

• Node.js の LTS バージョンを する
• Safari、Chrome、Edge、Firefox の最新バージョン。

See our support policy for more details.

Prerequisites

• An Azure subscription
• A Storage Account

パッケージをインストールする

JavaScript 用の Azure Storage Data Lake クライアント ライブラリをインストールする場合は、npm パッケージ マネージャーを使用することをお勧めします。 ターミナル ウィンドウに次のように入力します。

npm install @azure/storage-file-datalake

クライアントを認証する

Azure Storage では、いくつかの認証方法がサポートされています。 Azure Data Lake Storage サービスと対話するには、ストレージ クライアントのインスタンス (DataLakeServiceClient、DataLakeFileSystemClient、DataLakePathClient など) を作成する必要があります。 認証の詳細については、 の作成に関する サンプルを参照してください。

• Azure Active Directory
• Shared Key
• Shared Access Signature

Azure Active Directory

Azure Data Lake Storage サービスでは、Azure Active Directory を使用して API への要求を認証できます。 @azure/identity パッケージには、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。 作業を開始するための詳細とサンプルについては、 の README を参照してください。

Compatibility

このライブラリは、Node.js とブラウザーと互換性があり、LTS Node.js バージョン (>=8.16.0) と Chrome、Firefox、Edge の最新バージョンに対して検証されます。

Web Workers

このライブラリでは、ブラウザーで使用する場合、特定の DOM オブジェクトをグローバルに使用できる必要があります。Web ワーカーは既定では使用できません。 Web ワーカーでこのライブラリを動作させるには、これらをポリフィルする必要があります。

詳細については、Web Worker で Azure SDK for JS を使用するための ドキュメントを参照してください

このライブラリは、Web ワーカーで使用するときに外部ポリフィルを読み込む必要がある次の DOM API に依存します。

• document
• DOMParser
• Node
• XMLSerializer

Node.js とブラウザーの違い

Node.js とブラウザーのランタイムには違いがあります。 このライブラリの使用を開始するときは、"ONLY AVAILABLE IN NODE.JS RUNTIME" または "ONLY AVAILABLE IN BROWSERS"でマークされた API またはクラスに注意してください。

• ファイルが圧縮データを gzip または deflate 形式で保持し、それに応じてコンテンツ エンコードが設定されている場合、ダウンロード動作は Node.js とブラウザーで異なります。 Node.js では、ストレージ クライアントは圧縮形式でファイルをダウンロードしますが、ブラウザーではデータは圧縮解除形式でダウンロードされます。

Node.js でのみ使用できる機能、インターフェイス、クラス、または関数

• アカウント名とアカウント キーに基づく共有キーの承認
  • StorageSharedKeyCredential
• Shared Access Signature (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 portal と Azure Storage Explorer に移動し、ストレージ アカウントを見つけ、BLOB/キュー/ファイル/テーブル サービス用の新しい CORS ルールを作成します。

たとえば、デバッグ用に次の CORS 設定を作成できます。 ただし、運用環境の要件に合わせて設定を慎重にカスタマイズしてください。

• 許可される配信元: *
• 使用できる動詞: DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
• 許可されるヘッダー: *
• 公開されたヘッダー: *
• 最長有効期間 (秒): 86400

注意: Data Lake は現在、BLOB サービスの CORS 設定を共有しています。

Key concepts

Azure Data Lake Storage Gen2 は、次の目的で設計されました。

• 数百ギガビットのスループットを維持しながら、複数のペタバイト単位の情報を提供する
• 大量のデータを簡単に管理できます

DataLake Storage Gen2 の主な機能は次のとおりです。

• Hadoop 互換アクセス
• POSIX 権限のスーパー セット
• 低コストのストレージ容量とトランザクションの観点からコスト効率が高い
• ビッグ データ分析用に最適化されたドライバー

Data Lake Storage Gen2 の基本的な部分は、Blob Storage への階層型名前空間の追加です。 階層型名前空間は、効率的なデータ アクセスのために、オブジェクト/ファイルをディレクトリの階層に編成します。

以前は、クラウドベースの分析は、パフォーマンス、管理、セキュリティの領域で侵害する必要がありました。 Data Lake Storage Gen2 は、次の方法でこれらの各側面に対応します。

• 分析の前提条件としてデータをコピーまたは変換する必要がないため、パフォーマンスが最適化されています。 階層型名前空間により、ディレクトリ管理操作のパフォーマンスが大幅に向上し、全体的なジョブパフォーマンスが向上します。
• ディレクトリとサブディレクトリを使用してファイルを整理および操作できるため、管理が容易になります。
• ディレクトリまたは個々のファイルに対して POSIX アクセス許可を定義できるため、セキュリティは適用できます。
• Data Lake Storage Gen2 は低コストの Azure Blob Storage の上に構築されているため、コスト効率が実現されます。 追加機能により、Azure でビッグ データ分析を実行するための総保有コストがさらに削減されます。

Data Lake Storage には、次の 3 種類のリソースが用意されています。

• 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

• パッケージ をインポート
• data lake service クライアント を作成する
• 新しいファイル システム を作成する
• ファイル システムの を一覧表示する
• ディレクトリ を作成および削除する
• ファイル を作成する
• ファイル システム 内のパスを一覧表示する
• ファイルをダウンロードし、文字列 (Node.js) に変換
• ファイルをダウンロードして文字列に変換する (ブラウザー)

パッケージをインポートする

クライアントを使用するには、パッケージをファイルにインポートします。

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

または、必要な型のみを選択的にインポートします。

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

Data Lake Service クライアントを作成する

DataLakeServiceClient には、Data Lake サービスへの URL とアクセス資格情報が必要です。 また、必要に応じて、options パラメーターの一部の設定を受け入れます。

パッケージからの DefaultAzureCredential@azure/identity 使用

DataLakeServiceClient をインスタンス化するための推奨される方法

Notice. Azure Data Lake では現在、AAD OAuth 認証の後に "ストレージ BLOB データ所有者" などの BLOB 関連ロールが再利用されます。

セットアップ : リファレンス - クライアント アプリケーションから Azure Active Directory を使用して BLOB (データ レイク) とキューへのアクセスを承認する - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

• 新しい AAD アプリケーションを登録し、サインインしているユーザーの代わりに Azure Storage にアクセスするためのアクセス許可を付与します。

  • 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 Storage にアクセスできるようになります。

• Azure Portal で RBAC を使用して Azure Data Lake データへのアクセスを許可する

  • BLOB (データ レイク) とキューの RBAC ロール - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal。
  • Azure portal で、ストレージ アカウントに移動し、ストレージ BLOB データ共同作成者 ロールを 、(azure-portal のストレージ アカウントの左側のナビゲーション バーにある) Access control (IAM) タブから登録済みの AAD アプリケーションに割り当てます。

• サンプルの環境のセットアップ

  • 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 認証のサンプル を参照してください。

[注 - 上記の手順は Node.js専用です]

接続文字列の使用

または、完全な接続文字列を引数として使用して、DataLakeServiceClient 静的メソッドを使用して fromConnectionString() をインスタンス化することもできます。 (接続文字列は Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用可能]

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

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

StorageSharedKeyCredential

または、アカウント名とアカウント キーを引数として渡すことによって、DataLakeServiceClient を使用して StorageSharedKeyCredential をインスタンス化します。 (アカウント名とアカウント キーは、Azure portal から取得できます)。[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 トークンを使用する

また、共有アクセス署名 (SAS) を使用して DataLakeServiceClient をインスタンス化することもできます。 Azure Portal から SAS トークンを取得することも、generateAccountSASQueryParameters()を使用して SAS トークンを生成することもできます。

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 Storage サンプル (JavaScript)
• DataLake Storage サンプル (TypeScript)
• DataLake Storage のテスト ケース

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.