OneLake と Azure Blob Filesystem (ABFS)

Azure Blob Filesystem (ABFS) ↗ を使用して、Foundry を OneLake ↗、Azure Data Lake Storage Gen2 (ADLS Gen2)、およびその他の対応する Azure 製品に接続します。ABFS コネクターを使用すると、ファイルを Foundry に読み込み、Foundry から Azure に書き込むことができます。

対応している機能

データモデル

このコネクターは、あらゆる種類のファイルを Foundry データセットに転送できます。ファイル形式は保持され、転送中も転送後もスキーマは適用されません。データにアクセスするには、出力データセットに必要なスキーマを適用するか、下流のデータ加工を作成します。

パフォーマンスと制限事項

転送可能なファイルのサイズに制限はありません。ただし、ネットワークの問題により、大規模な転送が失敗する場合があります。特に、Foundry ワーカーで実行される同期は、実行時間が2日を超えると中断されます。ネットワークの問題を避けるため、ファイルサイズを小さくし、同期の実行ごとに取り込むファイル数を制限することを推奨します。同期は、頻繁に実行されるようにスケジュール設定できます。

セットアップ

1. Data Connection アプリケーションを開き、画面の右上にある + 新規ソースを選択します。
2. 利用可能なコネクターの種類から ABFS—Azure Data Lake Storage Gen2 を選択します。
3. 以下のセクションの情報を使用し、追加の設定プロンプトに従ってコネクターのセットアップを続けます。

Foundry でのコネクターのセットアップについては、詳しくはこちらをご覧ください。

認証

データをインポートするには、コネクターが Azure のファイルシステムの内容を list で一覧取得し、ファイルの内容を read で読み取る必要があります。この動作は、指定した接続資格情報に関連付けられたプリンシパルの認可パターンによって実現できます。

• 粗い粒度のアクセス制御であるロールベースのアクセス制御（RBAC）の場合、プリンシパルには、データがあるコンテナに対するストレージ BLOB データ閲覧者 ↗ロールが必要です。
• 細かい粒度のアクセス制御であるアクセス制御リスト（ACL）の場合、プリンシパルには、取り込み対象のファイルに対する読み取り ACL と、コンテナのルートからファイルの場所までのパスにあるすべてのディレクトリに対する実行 ACL が必要です。

ADLS Gen2 のアクセス制御について、詳しくはこちら ↗をご覧ください。

ABFS コネクターは、認証に関する次の設定オプションをサポートしています。推奨度の高い順に記載しています。

• クライアント資格情報（推奨）
• 共有アクセス署名
• ユーザー名とパスワード
• 更新トークン
• 共有キー
• ワークロード ID フェデレーション
• Azure マネージド ID（レガシー — 既存の Agent ワーカーソース向け）

クライアント資格情報（Foundry の直接接続で推奨）

クライアント資格情報 ↗は、Entra ID のアプリ登録 ↗（サービスプリンシパル）を利用します。この方法は、すべての直接接続で推奨されます。次の項目でクライアント資格情報認証を設定します。

共有アクセス署名

共有アクセス署名（SAS）↗認証では、有効期間が短く、スコープが厳密に限定された資格情報を提供するトークンを使用します。これらのトークンは、サービスが必要に応じて生成し、ごく短期間だけ使用するクライアントに配布できる場合に最も有用です。

コネクターには固定の SAS トークンが必要で、ストレージアカウントで認証するために有効期間の長いトークンを保存します。

共有アクセス署名トークン

SAS トークンを取得するには、Azure ガイド ↗に沿って進めてください。

トークンの例：

/container1/dir1?sp=r&st=2023-02-23T17:53:28Z&se=2023-02-24T01:53:28Z&spr=https&sv=2021-12-02&sr=d&sig=1gF9B%2FOnEmtYeDl6eB9tb0va1qpSBjZw3ZJuW2pMm1E%3D&sdd=1

通常は、ストレージコンテナレベルで SAS トークンを生成することを推奨します。Azure ポータルのコンテナ表示でストレージコンテナを見つけます（設定 > 共有アクセストークン）。ストレージアカウントレベルで SAS トークンを生成する必要がある場合（Azure ポータルのストレージアカウント表示のセキュリティ > ネットワーク > 共有アクセス署名）、必要最小限の権限は次のとおりです。

• "Allowed services": "Blob"
• "Allowed resource types": "Container" + "Object"
• "Allowed permissions": "Read" + "List"

SAS トークンを生成するときは、必ず次のパラメーターを設定してください。

署名付きプロトコル： 接続で https を必須にするように、spr ↗ を設定することを推奨します。

署名付きリソース： アクセスを許可するリソースの種類に基づいて、値を変更します ↗。

ユーザー名/パスワード

ユーザー名/パスワード ↗認証方式は OAuth プロトコルに従います。資格情報は、テナントの Azure ページ（たとえば、https://login.microsoftonline.com/<tenant-id>/oauth2/token）を使用して生成されます。<tenant-id> を接続先のテナントの ID に置き換えます。

次の設定を行います。

更新トークン

更新トークン ↗認可方式は OAuth プロトコルに従います。更新トークンを生成する方法は、Azure ドキュメント ↗を参照してください。

次の設定を行います。

共有キー

すべての Azure ストレージアカウントには、2個の共有キー ↗が付属しています。ただし、共有キーのスコープはコンテナレベルではなくストレージアカウントレベルであるため、本番環境での使用は推奨しません。共有キーにはデフォルトで管理者権限があり、ローテーションは手動操作で行います。

共有キーを取得するには、Azure ポータルで対象のストレージアカウントに移動し、セキュリティとネットワークセクションのアクセスキーを選択します。

ワークロード ID フェデレーション（OIDC）

Azure のワークロード ID フェデレーション ↗認可方式は、OpenID Connect (OIDC) プロトコルに従います。表示されるソースシステムの設定手順に従って、ワークロード ID フェデレーションを設定してください。OIDC と Foundry の連携の詳細については、ドキュメントを参照してください。

Azure マネージド ID（レガシー — Agent ワーカー接続）

Azure マネージド ID ↗ では、Foundry に資格情報を保存する必要はありません。データへの接続に使用するマネージド ID には、基盤となるストレージに対する適切な権限が必要です。

ネットワーク

Foundry で Azure 接続を実行する場合、Foundry がソースと通信できるようにネットワークアクセスを設定する必要があります。このプロセスは次の2つのステップで構成されます。

1. Foundry からソースへのエグレスを許可するネットワークアクセスを設定します。 Data Connection アプリケーションで、ソースに適切なエグレスポリシーを適用することで設定できます。Azure コネクターには、ストレージアカウントのドメインへのポート443でのネットワークアクセスが必要です。たとえば、abfss://file_system@account_name.dfs.core.windows.net に接続する場合、ストレージアカウントのドメインは account_name.dfs.core.windows.net です。Data Connection アプリケーションは、ソースに指定された接続情報に基づいて、適切なエグレスポリシーを提案します。
2. Azure ストレージコンテナの許可リストに Foundry を登録します。 Azure のドキュメント ↗に記載されているとおり、Azure ストレージアカウントの許可リストに Foundry の IP を登録することで設定できます。Foundry の IP の詳細は、Control Panel アプリケーションのネットワークのエグレスで確認できます。

設定オプション

コネクターには、次の追加の設定オプションがあります。

ルートディレクトリでは、次の形式がサポートされています。

• Azure Data Lake Storage Gen2 または Azure Blob Storage:

Copied!
1
abfss://file_system@account_name.dfs.core.windows.net/<directory>/

• Microsoft Fabric:

Copied!
1
abfss://file_system@onelake.dfs.fabric.microsoft.com/path/to/directory/

例：

• abfss://file_system@account_name.dfs.core.windows.net/ ↗ は、そのファイルシステムのすべての内容にアクセスします。
• abfss://file_system@account_name.dfs.core.windows.net/path/to/directory/ ↗ は、特定のディレクトリにアクセスします。
• abfss://file_system@onelake.dfs.fabric.microsoft.com/path/to/directory/ ↗ は、Microsoft OneLake の特定のディレクトリにアクセスします。

Azure Data Lake/Blob Storage からデータを同期する

ABFS コネクターは、ファイルベースの同期インターフェースを使用します。

データを Azure Data Lake/Blob Storage にエクスポートする

ABFS にエクスポートするには、まず ABFS コネクターのエクスポートを有効にします。次に、新しいエクスポートを作成します。

エクスポートタスク（レガシー）

データのエクスポートを開始するには、エクスポートタスクを設定する必要があります。エクスポート先のコネクターが含まれるプロジェクトフォルダーに移動します。コネクター名を右クリックし、Data Connection タスクを作成を選択します。

Data Connection の表示の左側パネルで、次の操作を行います。

1. ソース名が使用するコネクターと一致することを確認します。
2. inputDataset という名前の入力を追加します。入力データセットは、エクスポート対象の Foundry データセットです。
3. outputDataset という名前の出力を追加します。出力データセットは、タスクの実行、スケジュール設定、監視に使用されます。
4. 最後に、テキスト項目に YAML ブロックを追加して、タスクの設定を定義します。

左側パネルに表示されるコネクターと入力データセットのラベルには、YAML で定義された名前は反映されません。

エクスポートタスクの YAML を作成する際は、次のオプションを使用します。

rewritePaths

最初のキーがファイル名に一致する場合、キー内のキャプチャグループは値に置き換えられます。値自体には、ファイル名にメタデータを追加するための部分を含めることができます。

値に次の内容が含まれる場合：

• ${dt:javaDateExpression}：値のこの部分は、ファイルがエクスポートされる時点のタイムスタンプに置き換えられます。javaDateExpression は DateTimeFormatter ↗ のパターンに従います。
• ${transaction}：値のこの部分は、このファイルを含むトランザクションの Foundry トランザクションIDに置き換えられます。
• ${dataset}：値のこの部分は、このファイルを含むデータセットの Foundry データセットIDに置き換えられます。

例：

Foundry データセット内の「spark/file_name」という名前のファイルが、ID が transaction_id のトランザクションに含まれ、データセットIDが dataset_id である場合を考えます。キーとして式 fi.*ame を、値として file_${dt:DD-MM-YYYY}-${transaction}-${dataset}_end を使用すると、ファイルが Azure に書き込まれる際に、spark/file_79-03-2023-transaction_id-dataset_id_end として保存されます。

フラグファイル

コネクターは、特定のビルドのすべてのデータがコピーされた後に、空のフラグファイルを Azure Storage に書き込むことができます。この空のファイルは、内容を利用する準備が整い、以後変更されないことを示します。フラグファイルは directoryPath に書き込まれます。ただし、createTransactionFolders が有効な場合、内容が書き込まれたフォルダーごとにフラグファイルが作成されます。フラグファイルが有効で、その名前が confirmation.txt の場合、ビルドでエクスポートするファイルの書き込みが完了した後に、すべてのフラグファイルが一度に書き込まれます。フラグファイルは、サブフォルダーがエクスポートされた時点ではなく、ビルドの最後に書き込まれます。

Azure 内のファイルがフラグファイルより新しい場合、通常は、前回のエクスポートが成功しなかったか、そのフォルダーでエクスポートが進行中であることを示します。

エクスポートタスクを設定したら、右上隅の保存を選択します。

仮想テーブル

このセクションでは、Azure Data Lake Storage Gen 2（Azure Blob Storage）ソースの仮想テーブルを使用する際の詳細について説明します。Foundry データセットに同期する場合、このセクションは適用されません。

次のテーブルは、ADLS Gen2 でサポートされている仮想テーブルの機能を示しています。

ADLS Gen2 に保存されたテーブルを入力または出力として使用できる、サポート対象の Foundry ワークフローの詳細については、仮想テーブルのドキュメントを参照してください。

ソース設定の要件

仮想テーブルを使用する際は、次のソース設定の要件に留意してください。

• Foundry ワーカーのソースを使用する必要があります。仮想テーブルは Agent ワーカー接続の使用に対応していません。
• このドキュメントのネットワーキングセクションの説明に従って、双方向接続と許可リスト登録が設定されていることを確認してください。
• Code Repositories で仮想テーブルを使用する場合は、必要な追加のソース設定について、仮想テーブルのドキュメントを参照してください。
• ソースの資格情報を設定する際は、クライアント資格情報、username/password、ワークロード ID フェデレーションのいずれかを使用する必要があります。仮想テーブルを使用する場合、ほかの資格情報の選択肢は利用できません。

Delta

仮想テーブルを元にしたパイプラインでインクリメンタル処理を有効にするには、ソースの Delta テーブルで Change Data Feed ↗ が有効になっていることを確認してください。Python トランスフォームの current および added 読み取りモードに対応しています。_change_type、_commit_version、_commit_timestamp 列が Python トランスフォームで利用可能になります。

Iceberg

Apache Iceberg テーブルを元にした仮想テーブルを読み込むには、Iceberg カタログが必要です。Iceberg カタログの詳細については、Apache Iceberg のドキュメント ↗を参照してください。ソースに登録されたすべての Iceberg テーブルは、同じ Iceberg カタログを使用する必要があります。

デフォルトでは、S3 内の Iceberg メタデータファイルを使用してテーブルが作成されます。テーブルを登録する際は、これらのメタデータファイルの場所を示す warehousePath を指定する必要があります。

Databricks で Delta Universal Format（UniForm）を使用する場合、Unity Catalog ↗ を Iceberg カタログとして使用できます。この統合の詳細については、Databricks のドキュメント ↗を参照してください。カタログは、ソースの接続情報タブで設定できます。Unity Catalog に接続するには、エンドポイントと個人用アクセストークンを指定する必要があります。テーブルは catalog_name.schema_name.table_name という命名パターンで登録してください。

Polaris ↗ は、Azure Data Lake Storage Gen2 に保存されたテーブルの Iceberg カタログとして使用できます。カタログは、ソースの接続情報タブで設定できます。

インクリメンタル処理は Iceberg のインクリメンタル読み取り ↗を使用し、現在は追加のみに対応しています。Python トランスフォームの current および added 読み取りモードに対応しています。

Parquet

Parquet を使用する仮想テーブルは、スキーマ推論を使用します。スキーマの判定には最大100個のファイルが使用されます。

トラブルシューティング

既知のエラーのトラブルシューティングには、以下のセクションを参照してください。

リソースが指定された HTTP メソッド HEAD に対応していません

Blob Storage ではなく、DFS の場所を使用していることを確認してください。

例：

Copied!
1
2
3
4
# 正しい例：
abfsRootDirectory: 'abfss://<account_name>.dfs.core.windows.net/'
# 誤った例：
abfsRootDirectory: 'abfss://<account_name>.blob.core.windows.net/'

このエンドポイントは BlobStorageEvents または SoftDelete に対応していません。このエンドポイントを使用する場合は、これらのアカウント機能を無効にしてください

magritteabfs.source.org.apache.hadoop.fs.FileAlreadyExistsException: Operation failed:
"This endpoint does not support BlobStorageEvents or SoftDelete. Please disable these
account features if you would like to use this endpoint.", 409, HEAD,
https://STORAGE_ACCOUNT_NAME.dfs.core.windows.net/CONTAINER_NAME/?
upn=false&action=getAccessControl&timeout=90

このエラーは、Hadoop ABFS が現在、SoftDelete を有効にしたアカウントに対応していない ↗ために発生します。唯一の解決策は、ストレージアカウントでこの機能を無効にすることです。

AADToken: AzureAD からトークンを取得するための HTTP 接続に失敗しました。HTTP レスポンス: 401 Unauthorized

Client Credentials 認証メカニズムには既知の問題 ↗があります。+ または / を含むサービスプリンシパルのクライアントシークレットは、Data Connection のインターフェースを使用して設定した場合、機能しません。この問題を解決するには、+ または / を含まない新しい資格情報を作成します。この問題が解消しない場合は、Palantir の担当者にお問い合わせください。

Data Connection Agent の外部でマネージド ID フローが機能することを確認する

トラブルシューティングでは、アクセスの問題とネットワークの問題を切り分けることを推奨します。そのためには、まずソースデータへのアクセスを（Data Connection の外部で）独立してテストします。次に、マネージド ID ↗ を使用して、Data Connection の VM からストレージアカウントへの接続を正常に確立できることを確認します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# ローカルのメタデータエンドポイントを使って新しいトークンを取得します。
# マシンに jq がない場合は、API 呼び出しの結果に含まれる access_token キーの値を
# TOKEN 環境変数に手動でエクスポートできます。
export TOKEN=`curl 'http://IP_ADDRESS_OF_VM/metadata/identity/oauth2/token?api-version=2018-02-01
&resource=https%3A%2F%2Fstorage.azure.com%2F' -H Metadata:true | jq '.access_token' | sed 's/"//g'`

# トークンが正しく設定されていることを確認してください。これは OAuth2 トークンである必要があります。たとえば `eyJ0e...`（引用符なし）です。
echo $TOKEN

# コンテナのルートの内容を一覧表示します。
curl -XGET -H "x-ms-version: 2018-11-09" -H "Authorization: Bearer $TOKEN"
"https://STORAGE_ACCOUNT_NAME.dfs.core.windows.net/CONTAINER_NAME?resource=filesystem&recursive=false"

# コンテナ内のファイルの内容を表示します。
curl -XGET -H "x-ms-version: 2018-11-09" -H "Authorization: Bearer $TOKEN"
"https://STORAGE_ACCOUNT_NAME.dfs.core.windows.net/CONTAINER_NAME/path/to/file.txt"

AADToken: AzureAD からトークンを取得するための HTTP 接続に失敗しました。HTTP レスポンス: 400 Bad Request

Azure マネージド ID の場合、このメッセージは、VM 上でトークンの取得に使用するメタデータエンドポイントに問題があることを示している可能性が高いです。VM 自体が異常な状態にあるか、マネージド ID がまだ VM に割り当てられていない可能性があります。これをデバッグするには、上のセクションにある cURL コマンドを使用して、VM からトークンの取得を試みます。

で始まる HTML 504 ゲートウェイタイムアウトページが返される

ページに For support, please email us at... というテキストが含まれている場合、エラーの原因はネットワークの問題である可能性があります。Foundry と Agent がインストールされている VM の間、および Agent の VM とソースの間で、プロキシが適切に設定されていることを確認してください。ABFS プラグインはプロキシ設定を管理せず、Agent の設定に依存します。インターフェース上で Agent が正常と表示され、VM からターミナルを使用して Azure 上のファイルにアクセスできる場合は、Issue を作成して追加のサポートを依頼してください。

このリクエストには、このリソースの種類を使用してこの操作を実行する権限がありません。, 403, HEAD

このエラーは通常、権限が不足した SAS トークンが生成された場合に発生します。同期を作成しようとすると、ソース全体のプレビューは期待されるとおりに表示されますが、フィルターで範囲を絞り込んだプレビューではエラーが発生します。SAS トークンの生成方法については、共有アクセス署名のセクションを参照してください。

エクスポートファイルの場所が Magritte ファイルシステムを使用している

export-abfs-task を使用しているときに、指定した directoryPath ではなく root/opt/palantir/magritte-bootvisor/var/data/processes/bootstrapper/ にファイルがエクスポートされる場合は、ディレクトリ URL の末尾に / があることを確認してください。

例：

Copied!
1
2
3
4
# 正しい例：
abfsRootDirectory: 'abfss://STORAGE_ACCOUNT_NAME.dfs.core.windows.net/'
# 誤った例：
abfsRootDirectory: 'abfss://STORAGE_ACCOUNT_NAME.blob.core.windows.net'