データ接続と統合利用可能なコネクターFoundry

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

Foundry

Foundry コネクターを使用すると、Foundry のインスタンス間でデータを共有できます。このワークフローでは両方の Foundry インスタンスへのアクセスが必要で、一方のインスタンスを「ソース」、もう一方を「宛先」として指定します。データ接続プロセス全体を通じて、ユーザーはほとんどの操作を宛先インスタンスで実行します。

このコネクターは現在、入力としてのビューにも、制限付きビューにも対応していません。宛先インスタンスに取り込むデータセットは、まずソースインスタンス内で実体化する必要があります。

たとえば、red.palantirfoundry.com から blue.palantirfoundry.com へのデータ転送が必要なユースケースでは、セットアップの大部分とその後のインタラクションは、転送されたデータの最終的な宛先となるインスタンス blue.palantirfoundry.com で行います。以下で説明するワークフローは、エクスポートによってデータを書き込むのではなく、取り込みによってデータを読み取ります。

サポートされている機能

機能ステータス
一括インポート🟢 一般提供
ストリーミング取り込み🟢 一般提供
インクリメンタル(差分連携)取り込み🟢 一般提供
探索近日公開
仮想テーブル🟡 ベータ版
計算プッシュダウン利用不可
テーブルエクスポート利用不可
エクスポートタスク利用不可

セットアップ

  1. Data Connection アプリケーションを開き、画面右上の + 新規ソースを選択します。

  2. 利用可能なコネクターの種類から Foundry を選択します。

  3. インターネット経由の直接接続を使用するか、中継 Agent 経由で接続するかを選択します。Foundry コネクターを使用する Agent ベースの接続は、以前のバージョンの Java に対応していないため、Agent で少なくとも Java 21 を実行する必要があります。

  4. ソース Foundry インスタンスの hostname を入力します。この場合、blue.palantirfoundry.com は red.palantirfoundry.com からデータを取得するため、red.palantirfoundry.com がソースインスタンスです。

  5. 認証方法を選択します。

  6. 直接接続を使用する場合は、ソースインスタンスのエグレスポリシーを作成します。red.palantirfoundry.com から blue.palantirfoundry.com にデータを取り込むには、URL https://red.palantirfoundry.com のポート443に対するエグレスポリシーを作成します。従来のデータ接続とは異なり、ソースインスタンス内ですべての IP アドレスを許可リストに登録する必要があります。これは、Control Panel でネットワークイングレスの設定オプションを選択して行います。

  7. 以下の手順に従い、Control Panel のソースインスタンスのネットワークのイングレス拡張機能に宛先インスタンスの IP アドレスを追加して、ソースインスタンスのイングレス IP 許可リスト登録を設定します。

    1. 宛先インスタンスで Control Panel のネットワークのエグレス拡張機能に移動し、適切な IP アドレスを特定します。
    2. ソースインスタンスで Control Panel のネットワークのイングレス拡張機能を起動します。
    3. 既存のドキュメントを確認して、ネットワークイングレスを設定します。

Agent ベースの接続を作成する場合は、代わりに Agent のホストに基づいて適切な IP アドレスを指定する必要があります。ネットワークエグレスの設定時に IP を特定する方法について、詳しくはこちら。

Control Panel のネットワークのイングレス拡張機能にアクセスできない場合は、Palantir サポートにお問い合わせください。

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

認証

Foundry コネクターは、以下の認証方法をサポートしています。

クライアント資格情報(本番環境): 長期間使用する接続では、クライアント資格情報のみが許可されます。クライアント資格情報を作成するには、以下の手順に従います。

  1. 次のリンクを使用して Developer Console に移動します。
Copied!
1 https://<SOURCE_FOUNDRY_INSTANCE>.palantirfoundry.com/workspace/developer-console/
  1. + 新規アプリケーションを選択し、名前を入力します。
  2. いいえ、オントロジー SDK は使用しませんを選択し、所属する組織を選択した後、必ずアプリケーションを有効にするようにしてください。
  3. バックエンドサービスを選択します。
  4. アプリケーションに適切な権限を付与します。アプリケーションの権限またはユーザー権限を選択できますが、デフォルトではアプリケーションの権限を選択したままにしておくことを推奨します。
  5. クライアントシークレットが表示されます。これをクリップボードにコピーし、宛先 Foundry インスタンスに貼り付ける必要があります。
  6. 保存後、左側のナビゲーションパネルで[OAuth と制限]に移動します。
  7. クライアントIDをコピーします。

このプロセスにより、Foundry 内のアセットへのアクセスを付与または拒否できるサービスユーザーが作成されます。このサービスユーザーがデータセットまたはプロジェクトにアクセスできるかどうかを確認するには、対象のアセットでアクセスを確認機能を使用できます。

個人用アクセストークン(一時的): セキュリティ上の理由から、本番環境のユースケースではトークンの使用は許可されません。有効期間が36時間を超えるトークンを使用して同期を実行すると、取り込みに失敗します。

認証資格情報は宛先インスタンスに入力します。ソースインスタンスでは、宛先インスタンスがデータを読み取れるようにするトークンを作成する必要があります。そのためには、次の URL に移動します。

Copied!
1 https://<SOURCE_FOUNDRY_INSTANCE>.palantirfoundry.com/workspace/settings/tokens

次に、右上の + トークンを作成を選択します。このステップでは、トークンに名前を付け、有効期間を選択できます。その後、トークンをコピーし、宛先 Foundry インスタンスに移動します。

指定する資格情報には、以下の必要な権限が必要です。

  • ソース Foundry インスタンスのデータセットを参照および読み取る権限
  • 同期対象の特定のプロジェクトおよびデータセットを読み取る権限

ネットワーク

Foundry コネクターには、ポート443 (HTTPS) で宛先 Foundry インスタンスにアクセスできるネットワーク接続が必要です。宛先インスタンスには、ソースインスタンスの URL に対応するエグレスポリシーが必要です。

データフローはプル方式です。宛先エンロールメントがソースエンロールメントへのネットワーク接続を開始し、そこからデータを取得します。このため、宛先インスタンスにはソースインスタンスに到達するためのエグレスポリシーが必要であり、ソースインスタンスでは宛先インスタンスの IP アドレスをイングレスの許可リストに登録する必要があります。

Foundry インスタンスから別の Foundry インスタンスへの直接接続を有効にするには、Data Connection アプリケーションでソースをセットアップする際に、適切なエグレスポリシーを追加する必要があります。

Agent を使用する接続では、エグレスポリシーは不要です。

Foundry からデータを同期する

Foundry 間の同期を設定するには、ソースの概要画面の右上にある同期の探索と作成を選択します。ソースの Foundry インスタンスで利用可能なプロジェクトとデータセットの一覧を見て、同期するデータセットを選択します。準備ができたら、x個のデータセットの同期を作成を選択します。

権限とマーキング

認証を行うユーザーは、クライアント資格情報と個人用アクセストークンのどちらを使用する場合でも、ソースインスタンス上で閲覧権限を持つ任意のデータセットを同期できます。ユーザーがデータセットの所有者である必要はありません。

マーキングは Foundry インスタンス間で転送されないため、宛先インスタンスで同期されたデータに適切なセキュリティ制御を適用するプロセスを整備してください。特に、機密データや機密指定されたデータを移動する場合は重要です。

インクリメンタル(差分)同期

インクリメンタル同期、または APPEND 同期は、直近の同期に関する状態を保持し、対象データセットの新しいデータまたは変更されたデータのみを取り込みます。Foundry コネクターでこの取り込みを設定する方法は2つあります。

インクリメンタル同期の選択肢1:すべてのデータを取り込み、その後は更新のみを取り込む

「インクリメンタル同期の初期状態」は、1970年1月1日のように、任意の遠い過去の日付に設定できます。取り込みの初回実行では、すべてのデータが抽出されます。2回目以降の実行では、利用可能な最新のデータのみが抽出されます。

インクリメンタル同期の選択肢2:特定の日付以降のすべてのデータを取り込む

「インクリメンタル同期の初期状態」は、2024年1月1日のように、任意の日付に設定できます。上記の選択肢と同様に、取り込みの初回実行ではすべてのデータが抽出されます。その後の取り込みでは、利用可能な最新のデータのみが抽出されます。この選択肢では取り込むデータをより限定でき、取り込みの作成者が、特定の日付より前に外部ソースシステムに書き込まれたデータを除外したいとわかっているユースケースに適しています。

ストリーミング同期を作成する

ある Foundry エンロールメントから別のエンロールメントにストリームを取り込めます。ソースエンロールメントのデータセットはストリームである必要があります。データセットの RID とブランチ名を使用して同期を設定できます。スキーマを指定して初回実行すると、宛先エンロールメントに新しいデータセットが作成されます。

ストリーミングのオフセットオプション

同期は、新しく作成された行のみを取り込むように設定することも、ストリームの既存のすべての行を取り込んでから開始するように設定することもできます。考慮すべき主なトレードオフは、ストリーミングデータセットが十分に大きい場合、過去のすべての行の取り込みに時間とコンピューティングの面で大きなコストがかかる可能性があることです。

仮想テーブル

データセットは仮想テーブルに対応していません。「ソース」の Foundry インスタンス上のマネージド Iceberg テーブルのみを仮想化できます。

このセクションでは、Foundry ソースで仮想テーブルを使用する際の追加情報を説明します。Foundry データセットに同期する場合、このセクションは適用されません。

以下のテーブルは、Foundry で対応している仮想テーブルの機能を示しています。

機能ステータス
一括登録🔴 利用不可
自動登録🔴 利用不可
テーブル入力🟢 一般提供:Code Repositories、Pipeline Builder のテーブル
テーブル出力🟢 一般提供:Code Repositories、Pipeline Builder のテーブル
インクリメンタル(差分処理)パイプライン🟢 一般提供
コンピューティングのプッシュダウン🔴 利用不可

Foundry テーブルを入力または出力として使用できる対応ワークフローの詳細については、仮想テーブルのドキュメントを確認してください。

「宛先」の Foundry インスタンスから、「ソース」の Foundry インスタンスと、Iceberg テーブルの元となるバケットの場所にネットワーク経由でアクセスできることを確認してください。このバケットが「宛先」の Foundry インスタンスからのイングレスを許可していることを確認してください。

コードから Foundry API を呼び出す

上記の Foundry 間の同期ワークフローに加え、Python トランスフォームでは、OAuth2 クライアント資格情報グラントを使用して Foundry API を直接呼び出せます。このパターンは、同期として公開されていない Foundry エンドポイントを呼び出す必要がある場合に使用します。たとえば、トランスフォーム内からプロジェクトの内容を列挙する、ビルドをトリガーする、オントロジー API から読み取る場合などです。

全体の設定(REST API ソースの設定、client_id/client_secret の追加シークレットとしての保存、およびトークンリクエストとページネーションの汎用的な基本実装)は、ほかの OAuth2 クライアント資格情報フローと同じです。汎用的なパターンについては、REST API コネクターのページの OAuth クライアント資格情報グラントの例を確認してください。

以下のセクションでは、サードパーティ API とは異なる Foundry 固有の詳細を説明します。

Foundry トークンエンドポイント

Foundry の OAuth2 トークンエンドポイントは次のとおりです。

POST /multipass/api/oauth2/token

このエンドポイントは、呼び出し先の Foundry インスタンス上でホストされています。トランスフォームが呼び出し先と同じインスタンス上で実行される場合、REST API ソースの hostname はそのインスタンスを指します。別のインスタンスの場合、ソースの hostname は対象インスタンスを指し、ネットワークの説明に従ってエグレスポリシーとイングレスの許可リスト登録を設定する必要があります。

トークンエンドポイントのパラメーターについて、詳しくはこちら。

Foundry スコープ

Foundry API の各エンドポイントのドキュメントには、必要なスコープが記載されています。API ドキュメントのエンドポイント別リファレンスを参照してください。よく使われる例を以下に示します。

スコープ許可されるアクセス
api:datasets-readデータセットの読み取り
api:datasets-writeデータセットの書き込み
api:ontologies-readオントロジーのオブジェクトとリンクタイプの読み取り

トランスフォームに必要なスコープのみをリクエストします。複数のスコープは、api:datasets-read api:datasets-write のようにスペースで区切ります。

クライアントを作成する

トークンリクエストで使用する client_id と client_secret は、対象の Foundry インスタンスに登録されたサードパーティアプリケーションから取得します。上記の認証の手順に従ってバックエンドサービスアプリケーションを作成し、client_id と client_secret を取得してから、REST API ソースの追加シークレットとして保存します。

クライアント用に作成したサービスユーザーには、トランスフォームがアクセスする必要のあるすべてのプロジェクト、データセット、またはオントロジーリソースへの権限を付与する必要があります。

例:プロジェクトの子リソースを一覧表示する

以下のトランスフォームは、/multipass/api/oauth2/token に対してアクセストークンをリクエストし、そのトークンを使用して、Foundry の /api/v2/filesystem/resources/{rid}/children エンドポイント経由でプロジェクトの子リソースを一覧表示します。この例で再利用しているトークンリクエストとページネーションの汎用的な基本実装については、REST API の OAuth クライアント資格情報グラントの例を参照してください。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 import logging import pandas as pd from transforms.api import Output, transform_pandas from transforms.external.systems import external_systems, Source, ResolvedSource logger = logging.getLogger(__name__) @external_systems( foundry_api_source=Source("<source_rid>") ) @transform_pandas( Output("<output_dataset_rid>"), ) def compute(foundry_api_source: ResolvedSource) -> pd.DataFrame: base_url = foundry_api_source.get_https_connection().url client = foundry_api_source.get_https_connection().get_client() client_id = foundry_api_source.get_secret("additionalSecretClientId") client_secret = foundry_api_source.get_secret("additionalSecretClientSecret") token_response = client.post( base_url + "/multipass/api/oauth2/token", data={ "grant_type": "client_credentials", "client_id": client_id, "client_secret": client_secret, "scope": "api:datasets-read", }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) token_response.raise_for_status() access_token = token_response.json()["access_token"] auth_headers = {"Authorization": f"Bearer {access_token}"} project_rid = "ri.compass.main.folder.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" resources = [] page_token = None while True: params = {"pageSize": 100} if page_token: params["pageToken"] = page_token response = client.get( base_url + f"/api/v2/filesystem/resources/{project_rid}/children", headers=auth_headers, params=params, ) response.raise_for_status() body = response.json() for resource in body.get("data", []): resources.append({ "rid": resource.get("rid"), "name": resource.get("displayName"), "type": resource.get("type"), }) page_token = body.get("nextPageToken") if not page_token: break logger.info(f"Fetched {len(resources)} resources so far, continuing to next page.") return pd.DataFrame(resources)

トラブルシューティング

プレビューまたは同期が認証エラーで失敗する

ネットワーク接続の問題が疑われる場合は、スコープの問題を調査する前に、ソースインスタンスへの TLS 接続を確認してください。

プレビューまたは同期の操作が認証エラーで失敗する場合は、認証設定を確認します。

個人用アクセストークンの問題: 固定トークンはテストのみを目的としています。有効期間が36時間を超えるトークンは、実行時に拒否されます。本番環境の接続には OAuth を使用します。

クライアント資格情報の問題: クライアント資格情報を使用しているときに、プレビューが INVALID_ARGUMENT エラーで失敗する場合は、アプリケーションに設定された制限に問題がある可能性があります。厳しい制限によって、対象データセットへのアクセスがブロックされることがあります。これを解決するには、次の手順を実行します。

  1. ソースインスタンスの Developer Console で、サードパーティアプリケーションの設定に移動します。
  2. クライアント資格情報に割り当てられた制限を確認します。
  3. 対象データセットへのアクセスを妨げている可能性のある制限を削除または緩和します。
  4. 同期対象のデータセットに対して、サービスユーザーが適切な権限を持っていることを確認してください。

関連ドキュメント