注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
Foundry を Azure Data Lake Storage Gen2（ADLS Gen2）およびその他の対象となる Azure 製品に Azure Blob Filesystem (ABFS)（外部）を使用して接続します。ABFS コネクタを使用すると、ファイルを Foundry に読み込んだり、Foundry から Azure に書き込んだりできます。
Azure Data Lake Storage Gen1 への接続はサポートされていません。
| 機能 | ステータス |
|---|---|
| 一括インポート | 🟢 一般提供 |
| エクスポートタスク | 🟢 一般提供 |
| 探査 | 🟢 一般提供 |
| インクリメンタル | 🟢 一般提供 |
| 仮想テーブル | 🟢 一般提供 |
| メディアセット | 🟢 一般提供 |
コネクタは、Foundry データセット内に任意のタイプのファイルを転送できます。ファイル形式は保持され、転送中または転送後にスキーマは適用されません。出力データセットに必要なスキーマを適用するか、データにアクセスするために下流変換を記述してください。
転送可能なファイルのサイズに制限はありませんが、ネットワークの問題で大規模な転送が失敗することがあります。特に、2 日以上かかる直接のクラウド同期は中断されます。ネットワークの問題を回避するために、小さいファイルサイズを使用し、同期の実行ごとに取り込むファイルの数を制限することをお勧めします。同期はスケジュールに従って頻繁に実行できます。
ABFS コネクタでは、設定と構成を簡素化するために、直接接続を使用することをお勧めします。
Foundry でコネクタの設定について詳しく学ぶ。
データをインポートするには、コネクタは Azure でファイルシステムの内容をlistし、ファイルの内容をreadする必要があります。この動作は、提供された接続資格情報に関連付けられた主体の認証パターンを通じて実現できます。
Storage Blob Data Reader 役割が必要です。Read ACL が必要であり、コンテナルートからファイルの場所までのすべてのパスディレクトリに対して Execute ACL が必要です。ADLS Gen2 のアクセス制御について詳しく学ぶ。
ABFS コネクタは、以下の認証の構成オプションをサポートしており、最もお勧めから最もお勧めでない順にリストされています。
認証には Azure 管理 ID (外部リンク) の使用を推奨します。この認証メカニズムでは、資格情報を Foundry に保存する必要はありません。データに接続するために使用される管理 ID は、基盤となるストレージに適切な権限を持っている必要があります。
| オプション | 必須? | 説明 |
|---|---|---|
Tenant ID | いいえ | Tenant ID は Microsoft Entra ID (外部リンク) から取得できます。 |
Client ID | いいえ | エージェントが実行されている仮想マシン (VM) に複数の管理 ID (システムまたはユーザーによって割り当てられたもの) が接続されていた場合、ストレージに接続するために使用するべき ID を提供します。 |
管理 ID 認証方法は、仮想マシン (VM) 上のすべてのプロセスに利用可能なローカル REST エンドポイントに依存しています。この方法は、同じ Azure テナント内の VM 上にデプロイされたエージェントを通じて接続が行われる場合にのみ機能します。
クライアント資格情報 (外部リンク) は、Entra ID の アプリ登録 (Service Principal) に依存します。この方法は、すべての直接接続に対して優先されます。以下のフィールドでクライアント資格情報認証を設定します：
| オプション | 必須? | 説明 |
|---|---|---|
Client endpoint | はい | ユーザーの直接接続用の認証エンドポイントです。 通常、形式は https://login.microsoftonline.com/<directory-id>/oauth2/token で、<directory-id> はサブスクリプション ID です。詳細については、Azure の 公式ドキュメンテーション (外部リンク) を参照してください。 |
Client ID | はい | アプリ登録の ID で、アプリケーション ID とも呼ばれます。 |
Client secret | はい | アプリ登録で生成されたシークレットです。 |
共有アクセス署名 (SAS) (外部リンク) 認証は、短期間で厳密にスコープが定義された資格情報を提供するトークンを使用します。これらのトークンは、サービスが必要に応じて生成し、それを使用するクライアントに配布する場合に最も有用です。
| オプション | 必須? | 説明 |
|---|---|---|
Blob SAS token | はい | 共有アクセス署名トークン。 |
コネクターは静的な SAS トークンを必要とし、長期間有効なトークンをストレージアカウントで認証するために保存します。
一度 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""許可されたリソースタイプ": "コンテナ" + "オブジェクト""許可された権限": "読み取り" + "リスト"Azure Blob Storage に SAS トークンで接続するためには、Blob が保存されているリソースの ディレクトリを指定 (外部リンク) する必要があります。
SAS トークンを生成する際には、次のパラメーターを設定することを確認してください：
署名プロトコル: spr (外部リンク) を https を必須とするように設定することを推奨します。
署名リソース: アクセスが許可されるリソースタイプに基づいて 値を変更 (外部リンク) します。
使用中の署名リソースが指定されたディレクトリである場合、ディレクトリの深度 (外部リンク) も指定されていることを確認してください。我々は、接続がネストされたディレクトリからデータを引き出すことを許可するために、深度値を高く設定することを推奨します (例えば、sdd=100)。
ユーザー名/パスワード（外部）認証方法はOAuthプロトコルに従います。資格情報は、ユーザーのテナント用のAzureページ（例えば、https://login.microsoftonline.com/<tenant-id>/oauth2/token）を使用して生成されます。 <tenant-id>を接続しているテナントのIDに置き換えてください。
以下の設定を行ってください：
| オプション | 必須？ | 説明 |
|---|---|---|
Client endpoint | はい | OAuth設定からのクライアントエンドポイント。 |
Username | はい | ユーザーのメールアドレス。 |
Proxy password | はい | パスワードトークン。 |
再読み込みトークン（外部）認証方法はOAuthプロトコルに従います。Azureドキュメンテーション（外部）を使用して再読み込みトークンを生成する方法を学びます。
以下の設定を行ってください：
| オプション | 必須？ | 説明 |
|---|---|---|
Client ID | はい | クライアントID；Microsoft Entra IDで見つけることができます。 |
Refresh Token | はい | 再読み込みトークン。 |
すべてのAzureストレージアカウントには二つの共有キー（外部）が付属しています。しかし、共有キーはコンテナーレベルではなく、ストレージアカウントレベルでスコープが設定されているため、本番環境での使用はお勧めしません。共有キーはデフォルトで管理者権限を持っており、その回転は手動操作です。
共有キーを取得するには、Azureポータルで目的のストレージアカウントに移動し、Security + networkingセクションの下でAccess keysを選択します。
| オプション | 必須？ | 説明 |
|---|---|---|
Account key | はい | アカウントアクセスキー。 |
Azureへの直接接続を設定する際には、Foundryがソースと通信できるようにネットワークアクセスを設定する必要があります。これは二段階のプロセスです：
port 443で必要とします。例えば、abfss://file_system@account_name.dfs.core.windows.netに接続している場合、ストレージアカウントのドメインはaccount_name.dfs.core.windows.netです。Data Connectionアプリケーションは、ソースに提供された接続詳細に基づいて適切な出力ポリシーを提案します。Foundryのエンロールメントと同じAzureリージョンにホストされているAzureストレージバケットへのアクセスを設定している場合は、上記とは異なるネットワーク設定をPrivateLink経由で設定する必要があります。この場合は、Palantirの管理者に連絡してサポートを求めてください。
コネクターには以下の追加設定オプションがあります：
| オプション | 必須？ | 説明 |
|---|---|---|
Root directory | はい | データを読み書きするディレクトリ。 |
ルートディレクトリは次の形式で指定する必要があります：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（外部）特定のディレクトリにアクセスします。SASトークンで認証し、blobストレージにアクセスしている場合は、ルートディレクトリ設定でディレクトリを指定する必要があります。すべての内容は指定したディレクトリのサブフォルダー内にある必要があります。
ABFSコネクターは、ファイルベースの同期インターフェースを使用します。
コネクターは、FoundryデータセットからのファイルをAzureファイルシステム上の任意の場所にコピーすることができます。
データのエクスポートを開始するには、エクスポートタスクを設定する必要があります。エクスポートしたいコネクターが含まれているプロジェクトフォルダーに移動します。コネクター名を右クリックし、Create Data Connection Taskを選択します。
Data Connectionビューの左パネルで：
Source名が使用したいコネクターと一致していることを確認します。Inputという名前のinputDatasetを追加します。input datasetはエクスポートされるFoundryデータセットです。Outputという名前のoutputDatasetを追加します。output datasetはタスクの実行、スケジューリング、監視に使用されます。左側のパネルに表示されるコネクターと入力データセットのラベルは、YAMLで定義された名前を反映していません。
エクスポートタスクのYAMLを作成するときに以下のオプションを使用します：
| オプション | 必須？ | 説明 |
|---|---|---|
directoryPath | はい | ファイルが書き込まれるディレクトリ。パスは末尾に/が必要です。 |
excludePaths | いいえ | 正規表現のリスト；これらの表現に一致する名前のファイルはエクスポートされません。 |
rewritePaths | いいえ | 下記セクションを参照してください。 |
uploadConfirmation | いいえ | 値がexportedFilesの場合、出力データセットにはエクスポートされたファイルのリストが含まれます。 |
createTransactionFolders | いいえ | 有効にすると、データは指定されたdirectoryPath内のサブフォルダーに書き込まれます。すべてのサブフォルダーは、Foundryでコミットされた時間に基づいて、Foundryのすべてのエクスポートトランザクションに対して一意の名前を持ちます。 |
incrementalType | いいえ | データセットがインクリメンタルに構築されている場合、前回のエクスポート以降に行われたトランザクションのみをエクスポートするためにincrementalに設定します。 |
flagFile | いいえ | 下記セクションを参照してください。 |
spanMultipleViews | いいえ | trueの場合、Foundryの複数のトランザクションが一度にエクスポートされます。falseの場合、単一のビルドは一度に一つのトランザクションしかエクスポートしません。インクリメンタルが有効になっている場合、最も古いトランザクションのファイルが最初にエクスポートされます。 |
rewritePaths最初のキーがファイル名と一致する場合、キーのキャプチャグループは値に置き換えられます。値自体はファイル名にメタデータを追加するための追加セクションを持つことができます。
値に以下が含まれている場合：
${dt:javaDateExpression}：この値の部分は、ファイルがエクスポートされている時点のタイムスタンプに置き換えられます。javaDateExpressionはDateTimeFormatter（外部）のパターンに従います。${transaction}：この値の部分は、このファイルを含むトランザクションのFoundryトランザクションIDに置き換えられます。${dataset}：この値の部分は、このファイルを含むデータセットのFoundryデータセットIDに置き換えられます。例：
"spark/file_name"という名前のファイルがFoundryデータセットに存在し、そのトランザクション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データセットへの同期には適用されません。
| 仮想テーブルの能力 | ステータス |
|---|---|
| ソースフォーマット | 🟢 一般的に利用可能：Deltaテーブル、Parquetテーブル |
| 手動登録 | 🟢 一般的に利用可能 |
| 自動登録 | 🔴 利用不可 |
| プッシュダウン計算 | 🔴 利用不可 |
| インクリメンタルパイプラインのサポート | 🟢 Deltaテーブルに対して一般的に利用可能：APPENDのみ 🔴 Parquetテーブルに対して利用不可 |
仮想テーブルを使用する際には、以下のソース設定要件を覚えておいてください：
client credentialsまたはusername/passwordのいずれかを使用する必要があります。他の資格情報オプションは、仮想テーブルを使用する場合にはサポートされていません。また、仮想テーブルによって支えられたパイプラインのインクリメンタルサポートを有効にするためには、ソースDeltaテーブルでChange Data Feed（外部）が有効になっていることを確認してください。
以下のセクションを使用して、既知のエラーをトラブルシューティングします。
blobストレージではなく、DFSの場所を使用していることを確認してください。
例：
Copied!1 2 3 4 5# 正しい: abfsRootDirectory: 'abfss://<account_name>.dfs.core.windows.net/' # abfsルートディレクトリを設定します。ここではAzure Data Lake Storage Gen2のURIを使用します。 # 不正確: abfsRootDirectory: 'abfss://<account_name>.blob.core.windows.net/' # これは誤ったURIです。'blob.core.windows.net'ではなく、'dfs.core.windows.net'を使用する必要があります。
magritteabfs.source.org.apache.hadoop.fs.FileAlreadyExistsException: 操作が失敗しました:
"このエンドポイントは、BlobStorageEventsまたはSoftDeleteをサポートしていません。 このエンドポイントを使用したい場合は、
これらのアカウント機能を無効にしてください。", 409, HEAD,
https://STORAGE_ACCOUNT_NAME.dfs.core.windows.net/CONTAINER_NAME/?
upn=false&action=getAccessControl&timeout=90
# このエラーメッセージは、ファイルが既に存在することを示しています。
# また、このエンドポイントはBlobStorageEventsやSoftDeleteをサポートしていないことを示しています。
# これらの機能を使用したい場合は、アカウントの設定で無効にする必要があります。
このエラーは、Hadoop ABFSが現在 SoftDelete が有効な (外部の) アカウントをサポートしていないために発生します。唯一の解決策は、ストレージアカウントのこの機能を無効にすることです。
Client Credentials 認証メカニズムに既知の問題 (外部)があります。+ または / を含む Service Principal クライアントシークレットは、Data Connection インターフェースを使用して設定した場合には機能しません。この問題を解決するには、+ または / を含まない新しい資格情報を作成します。この問題が続く場合は、ユーザーの Palantir 代表に連絡してください。
トラブルシューティング中、アクセス問題とネットワーク問題を分けることをお勧めします。これを行うには、まずソースデータへのアクセスを独立して (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"
Azure Managed Identity の場合、このメッセージは、VM でトークンを取得するために使用されるメタデータエンドポイントに問題があることを意味する可能性があります。VM 自体が不良な状態にあるか、管理されたアイデンティティがまだ VM にアタッチされていない可能性があります。この問題をデバッグするには、上記のセクションで説明されている cURL コマンドを使用して、VM からトークンを取得しようとしてください。
ページに For support, please email us at... というテキストが含まれている場合、エラーはネットワークの問題から発生している可能性があります。Foundry とエージェントがインストールされている VM の間、およびエージェント VM とソースの間でプロキシが正しく設定されていることを確認してください。エージェントがインターフェースで正常に表示され、VM からターミナルを使用して Azure 上のファイルにアクセスできる場合は、追加のサポートを求めるために問題を報告してください。
ABFS プラグインはプロキシ設定を管理せず、エージェント設定に依存します。
このエラーは、通常、権限が不十分な SAS トークンが生成された場合に発生します。同期を作成しようとすると、ソース全体のプレビューが表示されることが期待されますが、フィルター処理された範囲が狭まったプレビューではエラーが発生します。SAS トークンの生成方法については、共有アクセスシグネチャセクションを参照してください。
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'
このコードのコメントはすでに明確であり、日本語に翻訳する必要はありません。しかし、必要であれば以下のようになります。
Copied!1 2 3 4# 正しい設定: abfsRootDirectory: 'abfss://STORAGE_ACCOUNT_NAME.dfs.core.windows.net/' # 不正な設定: abfsRootDirectory: 'abfss://STORAGE_ACCOUNT_NAME.blob.core.windows.net'
ここでは、Azure Blob File System (ABFS) のルートディレクトリの正しいと不正な設定方法を示しています。正しい設定では、'dfs.core.windows.net' を使用していますが、不正な設定では 'blob.core.windows.net' を使用しています。これは、ABFS は Data Lake Storage Gen2 で使用されるため、'blob.core.windows.net' ではなく 'dfs.core.windows.net' を使用する必要があるからです。