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

[アーティクル]
05/13/2024

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

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

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

ファイルシステムのCreate/リスト/削除
Create/読み取り/リスト/更新/削除パス、ディレクトリ、ファイル

キーリンク:

はじめに

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

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

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

前提条件

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

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

npm install @azure/storage-file-datalake

クライアントを認証する

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

Azure Active Directory
共有キー
共有アクセス署名

Azure Active Directory

Azure Data Lake Storage サービスでは、Azure Active Directory を使用して API への要求を認証できます。 @azure/identity パッケージには、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。作業を開始するための @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 とブラウザーのランタイムには違いがあります。このライブラリの使用を開始するときは、 "NODE.JS ランタイムでのみ使用可能" または "ブラウザーでのみ使用可能 " でマークされた API またはクラス に注意してください。

ファイルが圧縮されたデータをまたは deflate 形式でgzip保持し、そのコンテンツエンコードがそれに応じて設定されている場合、ダウンロード動作は 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 バンドル

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

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 ストレージに階層型名前空間を追加したものです。階層型名前空間には、効率的なデータアクセスのためにオブジェクトやファイルがディレクトリ階層に編成されています。

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

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

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

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

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

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

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

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

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

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

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

データレイクサービスクライアントをCreateする

には DataLakeServiceClient 、データレイクサービスへの 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 で、ストレージアカウントに移動し、(azure-portal のストレージアカウントの左側のナビゲーションバーにある) タブからAccess control (IAM)登録済みの AAD アプリケーションにストレージ BLOB データ共同作成者ロールを割り当てます。
サンプルの環境のセットアップ
- AAD アプリケーションの概要ページで、と TENANT IDをCLIENT IDメモします。 [Certificates & Secrets]\(証明書 & シークレット\) タブで、シークレットを作成し、下にメモします。
- サンプルを正常に実行するための環境変数として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);

with `StorageSharedKeyCredential`

または、account-name と account-key を引数として渡すことによって、を使用してをインスタンス化DataLakeServiceClientStorageSharedKeyCredentialします。 (アカウント名とアカウントキーは、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 トークンを使用する

また、Shared Access Signature (SAS) を使用してをインスタンス化 DataLakeServiceClient することもできます。 Azure Portal から SAS トークンを取得するか、を使用して SAS トークンを 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する

を使用して 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();

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

関数を使用して、新しいfor-await-of構文を使用DataLakeServiceClient.listFileSystems()してファイルシステムを反復処理します。

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

ディレクトリのCreateと削除

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.17.0

はじめに

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

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

JavaScript バンドル

CORS

主要な概念

例

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

データレイクサービスクライアントをCreateする

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

接続文字列の使用

with `StorageSharedKeyCredential`

SAS トークンを使用する

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

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

ディレクトリのCreateと削除

ファイルを作成する

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

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

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

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

次の方法で共有

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

はじめに

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

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

JavaScript バンドル

CORS

主要な概念

例

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

データ レイク サービス クライアントをCreateする

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

接続文字列の使用

with StorageSharedKeyCredential

SAS トークンを使用する

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

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

ディレクトリのCreateと削除

ファイルを作成する

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

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

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

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

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

データレイクサービスクライアントをCreateする

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

with `StorageSharedKeyCredential`

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

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

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