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

[アーティクル]
07/24/2024

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

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

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

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

キーリンク:

ソースコードの
パッケージ (npm)
API リファレンスドキュメント
製品のドキュメント
サンプル
Azure Storage Data Lake REST API をする

はじめ

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

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

詳細については、サポートポリシーのを参照してください。

前提条件

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

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 Access Signature

Azure Active Directory

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

互換性

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

Web Worker

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

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

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

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

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

JavaScript バンドル

ブラウザーでこのクライアントライブラリを使用するには、まず、バンドルを使用する必要があります。これを行う方法の詳細については、バンドルドキュメントを参照してください。

CORS

ブラウザー用に開発する必要がある場合は、ストレージアカウントクロスオリジンリソース共有 (CORS) 規則を設定する必要があります。 Azure portal と Azure Storage Explorer に移動し、ストレージアカウントを見つけ、BLOB/キュー/ファイル/テーブルサービス用の新しい CORS ルールを作成します。

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

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

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

主な概念

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 種類のリソースが用意されています。

ストレージアカウントDataLakeServiceClient 経由で使用されます
DataLakeFileSystemClient 経由で使用されるストレージアカウント内の ファイルシステム
DataLakeDirectoryClient または DataLakeFileClient を介して使用されるファイルシステム内のパス

Azure DataLake Gen2	ブロッブ
ファイルシステム	コンテナ
パス (ファイルまたはディレクトリ)	ブロッブ

注: このクライアントライブラリは、階層型名前空間 (HNS) が有効になっているストレージアカウントのみをサポートします。

例

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

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

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

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

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

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

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

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

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

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

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

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

新しい AAD アプリケーションを登録し、サインインしているユーザーの代わりに Azure Storage にアクセスするためのアクセス許可を付与します。
- Azure Active Directory (azure-portal) に新しいアプリケーションを登録する - /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 ロール - /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 を利用できます)。

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

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

接続文字列の使用

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

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

const connStr = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connStr);

`StorageSharedKeyCredential`

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

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

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

さらに、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;
  let 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: 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();

トラブルシューティング

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、@azure/loggerで setLogLevel を呼び出すことによって、実行時にログを有効にすることもできます。

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

setLogLevel("info");

次の手順

その他のコードサンプル:

貢献

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション

次の方法で共有

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

はじめ

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

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

JavaScript バンドル

CORS

主な概念

例

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

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

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

接続文字列の使用

`StorageSharedKeyCredential`

SAS トークンを使用する

新しいファイルシステムを作成する

ファイルシステムを一覧表示する

ディレクトリの作成と削除

ファイルを作成する

ファイルシステム内のパスを一覧表示する

ファイルをダウンロードして文字列に変換する (Node.js)

ファイルをダウンロードして文字列に変換する (ブラウザー)

トラブルシューティング

次の手順

貢献

その他のリソース

次の方法で共有

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

はじめ

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

前提 条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

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

JavaScript バンドル

CORS

主な概念

例

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

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

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

接続文字列の使用

StorageSharedKeyCredential

SAS トークンを使用する

新しいファイル システムを作成する

ファイル システムを一覧表示する

ディレクトリの作成と削除

ファイルを作成する

ファイル システム内のパスを一覧表示する

ファイルをダウンロードして文字列に変換する (Node.js)

ファイルをダウンロードして文字列に変換する (ブラウザー)

トラブルシューティング

次の手順

貢献

その他のリソース

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

前提条件

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

`StorageSharedKeyCredential`

新しいファイルシステムを作成する

ファイルシステムを一覧表示する

ファイルシステム内のパスを一覧表示する