Azure Blob Filesystem（ABFS）

Azure Blob Filesystem（ABFS) ↗を使用して、FoundryをAzure Data Lake Storage Gen2（ADLS Gen2）や他の対象となるAzure製品に接続します。ABFSコネクターを使用すると、ファイルをFoundryに読み込んだり、FoundryからAzureに書き込むことができます。

サポートされている機能

データモデル

コネクターを使用して、任意のタイプのファイルをFoundryデータセットに転送できます。ファイル形式は保持され、転送中や転送後にスキーマは適用されません。必要なスキーマを出力データセットに適用するか、データにアクセスするための下流変換を書きます。

パフォーマンスと制限

転送可能なファイルのサイズに制限はありません。しかし、ネットワークの問題により、大規模な転送が失敗することがあります。特に、2日以上かかる直接のクラウド同期は中断されます。ネットワークの問題を避けるために、私たちは小さなファイルサイズの使用と、同期の各実行で取り込まれるファイル数の制限を推奨します。同期は頻繁に実行するようにスケジュール設定できます。

設定

1. Data Connection アプリケーションを開き、画面右上の + 新規ソース を選択します。
2. 利用可能なコネクタタイプから ABFS—Azure Data Lake Storage Gen2 を選択します。
3. 直接接続を使用するか、中継エージェント経由で接続するかを選択します。
4. 以下のセクションにある情報を使用して、コネクタの設定を続けるための追加の設定プロンプトに従います。

Foundryでのコネクタの設定については、さらに詳しく学んでください。

認証

データをインポートするためには、コネクタがファイルシステムの内容をlistし、Azureでファイルの内容をreadする必要があります。この動作は、提供された接続資格情報に関連するプリンシパルの認証パターンを通じて達成できます。

• 役割ベースのアクセス制御（RBAC）の場合、粗大なアクセス制御形式では、プリンシパルがデータが配置されているコンテナにStorage Blob Data Reader ↗の役割が必要です。
• アクセス制御リスト（ACL）の場合、細かいアクセス制御形式では、プリンシパルがインジェストファイルにRead ACLを、コンテナのルートからファイルの場所までのすべてのパスディレクトリにExecute ACLを必要とします。

ADLS Gen2のアクセス制御について詳しく学ぶ ↗。

ABFSコネクタは、以下の認証のための設定オプションをサポートしています。推奨度の高い順にリスト化しています：

• Azure managed identity（エージェント接続に推奨）
• Client credentials（直接接続に推奨）
• Shared access signature
• Username and password
• Refresh token
• Shared key
• Workload Identity Federation

Azure 管理 ID (エージェント接続に推奨)

Azure 管理 ID ↗ を使用して認証することをお勧めします。この認証メカニズムは、資格情報を Foundry に保存する必要がありません。データに接続するための管理 ID は、基礎となるストレージに適切な権限を持つ必要があります。

クライアント資格情報 (直接接続に推奨)

クライアント資格情報 ↗ は 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ポータルのストレージアカウントビューで セキュリティ > ネットワーキング > 共有アクセス署名 にあります）、最小限の権限セットは以下の通りです:

• "許可されるサービス": "Blob"
• "許可されるリソースタイプ": "Container" + "Object"
• "許可される権限": "Read" + "List"

SASトークンを生成する際には、以下のパラメータを設定するようにしてください:

署名プロトコル: spr ↗を設定して、接続にhttpsを強制することを推奨します。

署名リソース: 値を変更 ↗して、アクセスが許可されているリソースタイプに基づきます。

ユーザー名/パスワード

ユーザー名/パスワード ↗ 認証方法は、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への直接接続を設定する際には、Foundryがソースと通信するためのネットワークアクセスを設定する必要があります。これは2ステップのプロセスです：

1. Foundryからソースへのネットワークアクセスを設定します。 これは、Data Connectionアプリケーションのソースに適切な出口ポリシーを適用することで行うことができます。Azureコネクタは、ストレージアカウントのドメインへのネットワークアクセスを必要とします。port 443。例えば、abfss://file_system@account_name.dfs.core.windows.netに接続している場合、ストレージアカウントのドメインはaccount_name.dfs.core.windows.netです。Data Connectionアプリケーションは、ソースで提供された接続詳細に基づいて適切な出口ポリシーを提案します。
2. AzureストレージコンテナからFoundryをホワイトリストに追加します。 これは、AzureのストレージアカウントからFoundryのIPをホワイトリストに追加することで行うことができます。詳細については、Azureのドキュメンテーション ↗を参照してください。FoundryのIP詳細は、Control PanelアプリケーションのNetwork Egressの下で見つけることができます。

設定オプション

コネクタには以下の追加設定オプションがあります：

ルートディレクトリは以下の形式で指定する必要があります： abfss://file_system@account_name.dfs.core.windows.net/<directory>。

例：

• abfss://file_system@account_name.dfs.core.windows.net/ ↗ そのファイルシステムのすべてのコンテンツにアクセスする。
• abfss://file_system@account_name.dfs.core.windows.net/path/to/directory ↗ 特定のディレクトリにアクセスする。

Azure Data Lake/Blob Storage からのデータ同期

ABFS コネクタは、file-based sync interface を使用します。

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

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

コネクタは、FoundryデータセットからAzureファイルシステム上の任意の場所にファイルをコピーできます。

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

データコネクションビューの左パネルで：

1. Sourceの名前が使用するコネクタと一致することを確認します。
2. inputDatasetという名前のInputを追加します。input datasetはエクスポートされるFoundryデータセットです。
3. outputDatasetという名前のOutputを追加します。output datasetはタスクの実行、スケジューリング、モニタリングに使用されます。
4. 最後に、テキストフィールドに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ストレージに空のフラグファイルを書き込むことができます。空のファイルは、内容が消費可能であり、これ以上変更されないことを示します。フラグファイルはdirectoryPathに書き込まれます。ただし、createTransactionFoldersが有効になっている場合、内容が書き込まれた各フォルダーにフラグファイルが作成されます。フラグファイルが有効であり、フラグファイルがconfirmation.txtと呼ばれる場合、すべてのフラグファイルは、ビルドでエクスポートされるファイルが書き込まれた後に一度に書き込まれます。

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

エクスポートタスクを設定した後、右上のSaveを選択します。

バーチャルテーブル

このセクションでは、Azure Data Lake Storage Gen 2（Azure Blob Storage）ソースからのバーチャルテーブルの使用に関する追加の詳細を提供します。このセクションは、Foundryデータセットへの同期時には適用されません。

バーチャルテーブルを使用する際は、以下のソース設定要件を覚えておいてください：

• ソースを直接接続として設定する必要があります。バーチャルテーブルは中間エージェントの使用をサポートしていません。
• このドキュメントのNetworkingセクションで説明されているように、双方向接続とホワイトリスト設定が確立されていることを確認します。
• コードリポジトリでバーチャルテーブルを使用する場合は、追加のソース設定要件の詳細については、バーチャルテーブルのドキュメントを参照してください。
• ソースの資格情報を設定する際には、client credentials、username/password、またはworkload identity federationのいずれかを使用する必要があります。バーチャルテーブルを使用する際には、他の資格情報オプションはサポートされていません。

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を提供する必要があります。

Unity Catalog ↗は、DatabricksでDelta Universal Format (UniForm)を使用する際にIcebergカタログとして使用できます。この統合の詳細については、Databricksドキュメント ↗をご覧ください。カタログはソースのConnection Detailsタブで設定できます。Unity Catalogに接続するために、エンドポイントとパーソナルアクセストークンを提供する必要があります。テーブルはcatalog_name.schema_name.table_nameの命名パターンを使用して登録する必要があります。

インクリメンタルサポートはIcebergのIncremental Reads ↗に依存しており、現在は追加のみです。Pythonトランスフォームのcurrentとaddedの読み取りモードがサポートされています。

Parquet

Parquetを使用したバーチャルテーブルはスキーマ推定に依存します。スキーマを決定するために最大100ファイルが使用されます。

トラブルシューティング

以下のセクションを使用して、既知のエラーのトラブルシューティングを行います。

このリソースは指定されたHTTP動詞HEADをサポートしていません

DFSロケーションを使用していること、blobストレージを使用していないことを確認してください。

例：

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認証メカニズムには既知の問題 ↗があります。サービスプリンシパルクライアントシークレットに+または/が含まれている場合、データ接続インターフェースを使用して設定すると動作しません。この問題を解決するには、+または/を含まない新しい資格情報を作成します。この問題が続く場合は、Palantir代表に連絡してください。

データ接続エージェントの外部で管理されたアイデンティティフローが機能することを確認する

トラブルシューティングを行う際、アクセス問題とネットワーク問題を分離することをお勧めします。これを行うには、まずソースデータへのアクセスを独立して（データ接続の外部で）テストします。次に、管理されたアイデンティティ ↗がデータ接続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 Managed Identityについては、このメッセージは通常、VMでトークンを取得するために使用されるメタデータエンドポイントに問題があることを意味します。VM自体が不良な状態にあるか、管理されたアイデンティティがまだVMにアタッチされていない可能性があります。これをデバッグするには、上記のセクションで記述されているcURLコマンドを使用してVMからトークンを取得しようとします。

HTML 504ゲートウェイタイムアウトページを受け取っています、で始まります

ページにFor support, please email us at...というテキストが含まれている場合、エラーはネットワーク問題から発生する可能性があります。FoundryとエージェントがインストールされたVMの間、およびエージェントVMとソースの間でプロキシが正しく設定されていることを確認します。エージェントがインターフェースで健康的に見え、VMを使用して端末からAzureのファイルにアクセスできる場合は、追加の支援を求めて問題を提出してください。

この操作をこのリソースタイプを使用して実行することは許可されていません。403、HEAD

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

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

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

例：

Copied!
1
2
3
4
# 正しい:
abfsRootDirectory: 'abfss://STORAGE_ACCOUNT_NAME.dfs.core.windows.net/'
# 不正確:
abfsRootDirectory: 'abfss://STORAGE_ACCOUNT_NAME.blob.core.windows.net'