Java 用 Azure File Data Lake クライアントライブラリ - バージョン 12.17.1

[アーティクル]
10/26/2023

Azure Data Lake Storageは、ビッグデータ分析ワークロード向けの Microsoft の最適化されたストレージソリューションです。 Data Lake Storage Gen2 の基礎部分は、BLOB ストレージに階層型名前空間を追加したものです。階層型名前空間には、効率的なデータアクセスのためにオブジェクトやファイルがディレクトリ階層に編成されています。

ソースコード | API リファレンスドキュメント | REST API のドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

GA バージョンのライブラリに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、バージョンタグのない依存関係セクションに直接依存関係を含めます。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-datalake</artifactId>
    <version>12.17.1</version>
</dependency>

ストレージアカウントを作成する

ストレージアカウントを作成するには、 Azure Portal または Azure CLI を使用できます。注: データレイクを使用するには、アカウントで階層型名前空間が有効になっている必要があります。

# Install the extension “Storage-Preview”
az extension add --name storage-preview
# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

ストレージアカウントの URL (後でとして <your-storage-account-url>識別されます) は、次のように書式設定されます。 http(s)://<storage-account-name>.dfs.core.windows.net

クライアントを認証する

ストレージサービスを操作するには、Service Client クラスのインスタンスを作成する必要があります。これを可能にするには、ストレージアカウントのアカウント SAS (共有アクセス署名) 文字列が必要です。詳細については、SAS トークンに関するページを参照してください

資格情報の取得

SAS トークン

a. 次の Azure CLI スニペットを使用して、ストレージアカウントから SAS トークンを取得します。

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

例:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. または、Azure Portal からアカウント SAS トークンを取得します。

ストレージアカウントに移動する
左側のメニューから選択 Shared access signature します
(セットアップ後) をクリックしますGenerate SAS and connection string

共有キーの資格情報

a. [アカウント名] と [アカウントキー] を使用します。アカウント名はストレージアカウント名です。

ストレージアカウントに移動する
左側のメニューから選択 Access keys します
[copy the contents of the field]\(フィールドの内容をコピーする\) の下key1/key2Key

または

b. 接続文字列を使用します。

ストレージアカウントに移動する
左側のメニューから選択 Access keys します
[copy the contents of the field]\(フィールドの内容をコピーする\) の下key1/key2Connection string

主要な概念

DataLake 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 Gen2には、次の 2 種類のリソースが用意されています。

_filesystem'DataLakeFileSystemClient' を介して使用される。
_path'DataLakeFileClient' または 'DataLakeDirectoryClient' を介して使用される。

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

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

URL 形式

パスは、次の URL 形式を使用してアドレス指定できます。次の URL はファイルをアドレス指定します。

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${myfile}

リソースの URI の構文

ストレージアカウントの場合、datalake 操作のベース URI には、アカウントの名前のみが含まれます。

https://${myaccount}.dfs.core.windows.net

ファイルシステムの場合、ベース URI にはアカウントの名前とファイルシステムの名前が含まれます。

https://${myaccount}.dfs.core.windows.net/${myfilesystem}

ファイル/ディレクトリの場合、ベース URI には、アカウントの名前、ファイルシステムの名前、パスの名前が含まれます。

https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${mypath}

上記の URI は、カスタムドメイン名などのより高度なシナリオでは保持されない場合があることに注意してください。

例

次のセクションでは、次のような最も一般的な Azure Storage BLOB タスクをカバーするいくつかのコードスニペットを示します。

を作成する DataLakeServiceClient
を作成する DataLakeFileSystemClient
を作成する DataLakeFileClient
を作成する DataLakeDirectoryClient
ファイルシステムを作成する
パスを列挙する
ファイルの名前を変更する
ディレクトリの名前を変更する
ファイルのプロパティを取得する
ディレクトリのプロパティを取得する
Azure Identity を使用して認証する

認証要求の処理に使用する `DataLakeServiceClient`

上記で DataLakeServiceClient 生成したを使用してを sasToken 作成します。

DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .buildClient();

または

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
    .buildClient();

認証要求の処理に使用する `DataLakeFileSystemClient`

を使用してを DataLakeFileSystemClient 作成します DataLakeServiceClient。

DataLakeFileSystemClient dataLakeFileSystemClient = dataLakeServiceClient.getFileSystemClient("myfilesystem");

または

上で DataLakeFileSystemClient 生成したビルダー sasToken からを作成します。

DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .buildClient();

または

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "?" + "<your-sasToken>")
    .buildClient();

認証要求の処理に使用する `DataLakeFileClient`

を使用してを DataLakeFileClient 作成します DataLakeFileSystemClient。

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");

または

上で FileClient 生成したビルダー sasToken からを作成します。

DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("myfile")
    .buildFileClient();

または

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeFileClient fileClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "myfile" + "?" + "<your-sasToken>")
    .buildFileClient();

認証要求の処理に使用する `DataLakeDirectoryClient`

を使用してを DataLakeDirectoryClient 取得します DataLakeFileSystemClient。

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");

または

上で DirectoryClient 生成したビルダー sasToken からを作成します。

DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>")
    .sasToken("<your-sasToken>")
    .fileSystemName("myfilesystem")
    .pathName("mydir")
    .buildDirectoryClient();

または

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
    .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "mydir" + "?" + "<your-sasToken>")
    .buildDirectoryClient();

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

を使用してファイルシステムを作成します DataLakeServiceClient。

dataLakeServiceClient.createFileSystem("myfilesystem");

または

を使用してファイルシステムを作成します DataLakeFileSystemClient。

dataLakeFileSystemClient.create();

パスを列挙する

を使用してすべてのパスを DataLakeFileSystemClient列挙する。

for (PathItem pathItem : dataLakeFileSystemClient.listPaths()) {
    System.out.println("This is the path name: " + pathItem.getName());
}

ファイルの名前の変更

を使用してファイルの名前を変更します DataLakeFileClient。

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
fileClient.rename("new-file-system-name", "new-file-name");

ディレクトリの名前を変更する

を使用してディレクトリの名前を DataLakeDirectoryClient変更します。

//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
directoryClient.rename("new-file-system-name", "new-directory-name");

ファイルのプロパティの取得

を使用してファイルからプロパティを取得します DataLakeFileClient。

DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
fileClient.create();
PathProperties properties = fileClient.getProperties();

ディレクトリのプロパティを取得する

を使用してディレクトリからプロパティを DataLakeDirectoryClient取得します。

DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
directoryClient.create();
PathProperties properties = directoryClient.getProperties();

Azure Identity を使用して認証する

Azure Identity ライブラリは、Azure Storage での認証に対する Azure Active Directory のサポートを提供します。

DataLakeServiceClient storageClient = new DataLakeServiceClientBuilder()
    .endpoint("<your-storage-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

トラブルシューティング

この Java クライアントライブラリを使用してデータレイクを操作する場合、サービスによって返されるエラーは、 REST API 要求に対して返されるのと同じ HTTP 状態コードに対応します。たとえば、ストレージアカウントに存在しないファイルシステムまたはパスを取得しようとすると、 404 を示す Not Foundエラーが返されます。

既定の HTTP クライアント

すべてのクライアントライブラリでは、Netty HTTP クライアントが既定で使用されます。前述の依存関係を追加すると、Netty HTTP クライアントを使用するようにクライアントライブラリが自動的に構成されます。 HTTP クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

既定の SSL ライブラリ

すべてのクライアントライブラリは、Tomcat ネイティブの Boring SSL ライブラリを既定で使用して、SSL 操作にネイティブレベルのパフォーマンスを実現しています。 Boring SSL ライブラリは、Linux、macOS、Windows のネイティブライブラリを含んだ uber jar であり、JDK 内の既定の SSL 実装よりも優れたパフォーマンスを備えています。依存関係のサイズを縮小する方法など、詳細については、Wiki の「パフォーマンスチューニング」セクションを参照してください。

次の手順

いくつかの Storage datalake Java SDK サンプルは、SDK の GitHub リポジトリで入手できます。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

Java 用 Azure File Data Lake クライアントライブラリ - バージョン 12.17.1

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

ストレージアカウントを作成する

クライアントを認証する

資格情報の取得

SAS トークン

共有キーの資格情報

主要な概念

URL 形式

リソースの URI の構文

例

認証要求の処理に使用する `DataLakeServiceClient`

認証要求の処理に使用する `DataLakeFileSystemClient`

認証要求の処理に使用する `DataLakeFileClient`

認証要求の処理に使用する `DataLakeDirectoryClient`

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

パスを列挙する

ファイルの名前の変更

ディレクトリの名前を変更する

ファイルのプロパティの取得

ディレクトリのプロパティを取得する

Azure Identity を使用して認証する

トラブルシューティング

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

共同作成

フィードバック

フィードバック

その他のリソース

Java 用 Azure File Data Lake クライアント ライブラリ - バージョン 12.17.1

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

ストレージ アカウントを作成する

クライアントを認証する

資格情報の取得

SAS トークン

共有キーの資格情報

主要な概念

URL 形式

リソースの URI の構文

例

認証要求の処理に使用する DataLakeServiceClient

認証要求の処理に使用する DataLakeFileSystemClient

認証要求の処理に使用する DataLakeFileClient

認証要求の処理に使用する DataLakeDirectoryClient

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

パスを列挙する

ファイルの名前の変更

ディレクトリの名前を変更する

ファイルのプロパティの取得

ディレクトリのプロパティを取得する

Azure Identity を使用して認証する

トラブルシューティング

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

共同作成

フィードバック

フィードバック

その他のリソース

Java 用 Azure File Data Lake クライアントライブラリ - バージョン 12.17.1

ストレージアカウントを作成する

認証要求の処理に使用する `DataLakeServiceClient`

認証要求の処理に使用する `DataLakeFileSystemClient`

認証要求の処理に使用する `DataLakeFileClient`

認証要求の処理に使用する `DataLakeDirectoryClient`

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