注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
外部トランスフォームを使用すると、Python トランスフォームのリポジトリから外部システムに接続できます。
Data Connection のソースをコードリポジトリに直接インポートできるようになりました。外部システムとの連携には、資格情報ベースのレガシー外部トランスフォームに代わり、この方法を推奨します。
外部トランスフォームは、認証にアウトバウンドアプリケーションを使用するソースをサポートしていません。
外部トランスフォームは主に、次のいずれかに該当する場合に、バッチ同期、エクスポート、およびメディア同期のワークフローを実行するために使用されます。
これらの状況への解決策として、次のような方法が考えられます。
仮想テーブルを使用するトランスフォームも、外部トランスフォームと見なされます。これは、トランスフォームジョブが、仮想化されたデータを含む外部システムにアクセスできる必要があるためです。Python トランスフォームで仮想テーブルを使用するには、以下の手順に従ってソースを設定してください。
このセットアップガイドでは、無料の公開辞書 API ↗ に接続する Python トランスフォームリポジトリを作成する手順を説明します。その後の例では、この API を使用して、外部トランスフォームのさまざまな機能と、API でそれらを使用する方法を説明します。
このセットアップガイドで使用する辞書 API は Palantir とは無関係であり、いつでも変更される可能性があります。このチュートリアルは、本番環境のユースケースでこの API を使用することを支持、推奨、提案するものではありません。
このガイドに沿って進める前に、まず Python トランスフォームリポジトリを作成し、チュートリアルで説明されている Python トランスフォームの作成方法を確認してください。Python トランスフォームのすべての機能は、外部トランスフォームでも利用できます。
Python リポジトリから外部システムに接続するには、コードにインポートできる Data Connection ソースを作成する必要があります。このチュートリアルでは、前述の辞書 API に接続する REST API ソースを作成します。
外部トランスフォームで使用するソースを作成する最も簡単な方法は、Python トランスフォームのコードリポジトリから作成することです。リポジトリを初期化したら、次のステップを実行して汎用ソースをセットアップします。
左側のパネルから、外部システムタブを開きます。
VS Code ワークスペースの Python トランスフォームリポジトリで作業している場合、外部システムの設定は上部ナビゲーションバーの設定タブにあります。
追加 > 新規作成を選択します。


このチュートリアルでは、辞書 API の api.dictionaryapi.dev に対するエグレスポリシーを追加してください。この API は認証を必要としないため、シークレットは不要です。また、エクスポート制御は現時点では省略できます。ただし、このソースで Foundry の入力データを使用するには、エクスポート制御が必要です。
この接続先は REST API であるため、組み込みの Python requests クライアントを使用できるように、汎用コネクターを REST API ソースに変換するためのダイアログが自動的に表示されます。
Data Connection アプリケーションからソースを作成するか、すでに設定済みの既存のソースを使用することもできます。この方法を使用するには、次のステップを実行します。

概要ページを確認し、右下の続行を選択します。接続ワーカーを選択するダイアログが表示されます。外部トランスフォームでは Agent ワーカー接続に対応していないため、辞書 API に接続するには Foundry ワーカーを選択します。
ソースの名前を選択し、保存先のプロジェクトを選択します。
ドメインセクションに API ソースの接続情報を入力します。辞書 API の例の設定を以下に示します。


ソースを作成しただけでは、リポジトリで利用できるようにはなりません。外部システムタブからこのソースを追加するには、前提条件:ソースをコードにインポートするの説明に従って、コードへのインポートを許可する必要があります。
transforms-external-systems ライブラリをインポートする外部トランスフォームを使用するには、まずリポジトリに transforms-external-systems ライブラリをインポートする必要があります。ライブラリをインストールするには、左側のパネルのライブラリタブで目的のライブラリを検索し、インストールを選択します。

複数のドメインを持つ REST API ソースはインポートできません。同じ外部トランスフォームで複数のドメインが必要な場合は、代わりにドメインごとに個別の REST API ソースを作成してください。
まず、REST API ソースのコードへのインポートを許可する必要があります。この設定を行うには、Data Connection でソースに移動し、接続設定 > コードインポート設定タブに移動します。
このソースを Code Repositories にインポートできるようにするオプションをオンにします。このソースをインポートするコードリポジトリは、このページに表示されます。


ソースをリポジトリにインポートするには、ソースに対して少なくとも編集者のアクセス権が必要です。権限について詳しくはこちら
Dictionary API ソースをインポートする Python トランスフォームリポジトリを設定したら、そのソースを使用して外部に接続する Python トランスフォームコードを記述できます。このページの後半にあるエンドツーエンドの例では、一般的なシステムを対象に、設定済みの読み取りおよび書き込みワークフローを示しています。
@external_systems デコレーターをインポートして設定する外部トランスフォームを使用するには、transforms.external.systems ライブラリから external_systems デコレーターと Source オブジェクトをインポートする必要があります。
Copied!1from transforms.external.systems import external_systems, Source
次に、external_systems デコレーターを使用して、トランスフォームに含めるソースを指定します。
Copied!1 2 3@external_systems( dictionary_api_source=Source("ri.magritte..source.e301d738-b532-431a-8bda-fa211228bba6") )
ソースは、Data Connection で開くためのリンクとして自動的に表示され、リソース識別子の代わりにソース名が表示されます。
ソースをトランスフォームにインポートすると、get_https_connection() メソッドで組み込みの接続オブジェクトを使用して、ソースの属性にアクセスできます。以下の例では、前のステップで設定した Dictionary API ソースのベース URL を取得する方法を示します。
Copied!1dictionary_api_url = dictionary_api_source.get_https_connection().url
ソースに保存されている追加のシークレットや資格情報にも、ソースからアクセスできます。アクセス可能なシークレット名を確認するには、トランスフォームの左側のパネルに移動します。

コード内でシークレットにアクセスするには、次の構文を使用します。
Copied!1dictionary_api_source.get_secret("additionalSecretFoo")
現在、ソースが HTTPS クライアントを提供していない場合、資格情報以外のソース属性にはアクセスできません。たとえば、PostgreSQL ソースでは、hostname やその他のシークレットではない属性にアクセスできません。
RESTful API を提供するソースでは、ソースオブジェクトを通じて組み込みの HTTPS クライアントを使用できます。このクライアントには、サーバー証明書やクライアント証明書を含め、ソースに指定されたすべての詳細があらかじめ設定されているため、そのまま外部システムへのリクエストを開始できます。
Copied!1 2 3 4 5 6dictionary_api_url = dictionary_api_source.get_https_connection().url dictionary_api_client = dictionary_api_source.get_https_connection().get_client() # dictionary_api_client は、Python の `requests` ライブラリの設定済み Session オブジェクトです。 # GET リクエストの例: response = dictionary_api_client.get(dictionary_api_url + "/api/v2/entries/en/" + word, timeout=10)
または、独自のクライアントやソース固有の Python ライブラリを使用し、ソースオブジェクトを使用して属性と資格情報を取得することもできます。ただし、Agent プロキシランタイム(サンセット)を使用してオンプレミスシステムに接続する場合は、組み込みクライアントを使用する_必要があります_。このクライアントには、必要な Agent プロキシ設定が自動的に適用されるためです。
トランスフォームや UDF 内で作業ディレクトリを変更すると(たとえば、os.chdir() を使用した場合)、安全な接続の確立に必要な環境変数への参照が機能しなくなる可能性があります。
以下の例は、単語のリストを順に処理し、Dictionary API からその発音表記を取得する完全なトランスフォームを示しています。
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 34from pandas import DataFrame from transforms.api import transform from transforms.api import Output, Input, TransformContext, transform_pandas from transforms.external.systems import external_systems, Source import pandas as pd import logging logger = logging.getLogger(__name__) @external_systems( dictionary_api_source=Source( "<source_rid>" ) ) @transform_pandas(Output("<output_dataset_rid>")) def compute(dictionary_api_source) -> DataFrame: dictionary_api_url = dictionary_api_source.get_https_connection().url dictionary_api_client = dictionary_api_source.get_https_connection().get_client() words = ["apple", "dog", "cat"] phonetics = [] for word in words: logger.info("Fetching word from api.dictionaryapi.dev : " + word) response = dictionary_api_client.get( dictionary_api_url + "/api/v2/entries/en/" + word ).json() phonetics += [{"word": word, "phonetic": response[0]["phonetic"]}] return pd.DataFrame(phonetics)
外部トランスフォームでは、Foundry の入力データを使用する必要があることがよくあります。たとえば、テーブル形式のデータセットの各行について追加のメタデータを収集するために、API にクエリを実行したい場合があります。また、Foundry のデータを外部のソフトウェアシステムにエクスポートする必要があるワークフローも考えられます。
このようなケースは、エクスポート制御の対象となるワークフローと見なされます。保護された Foundry データが、セキュリティの保証が不明な別のシステムに、データの来歴が途切れた状態でエクスポートされる可能性があるためです。ソース接続を設定する際、ソースの所有者は、Foundry からデータをエクスポートできるかどうかを指定し、エクスポート可能なセキュリティマーキングと組織を指定する必要があります。Foundry はガバナンス制御を提供し、開発者がセキュリティ上の意図を明確に設定に反映できるようにするとともに、情報セキュリティ責任者が外部システムとやり取りするワークフローの範囲と意図を監査できるようにします。
エクスポートは、セキュリティマーキングを使用して制御されます。ソースを設定する際、エクスポート設定を使用して、外部システムに安全にエクスポートできるセキュリティマーキングと組織を指定します。これを行うには、Data Connection アプリケーションでソースに移動し、接続設定 > エクスポート設定タブに移動します。次に、このソースへのエクスポートを有効化をオンにし、エクスポートする可能性のあるマーキングと組織を選択します。
これを行うには、関連するデータと組織のマーキングを解除する権限が必要です。エクスポートは、Foundry 内のデータのマーキングを解除することと同等と見なされるためです。
以下を可能にするには、このソースへのエクスポートを有効化の設定をオンにする必要があります。
以下は、Dictionary API ソースのエクスポート設定の例です。追加のセキュリティマーキングがない Palantir 組織のデータを Dictionary API にエクスポートすることを許可しています。

このシステムに実際にデータをエクスポートしない場合でも、このソースへのエクスポートを有効化をオンにする必要があります。このシステムへの接続が開かれている同じコンピューティングジョブに Foundry の入力データを許可すると、データがエクスポートされる_可能性がある_ためです。
この例では、ハードコードされた固定のリストの代わりに、単語の入力データセットを使用します。また、レスポンスのステータスコードに基づく基本的なエラー処理も示しています。
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 49from pandas import DataFrame from transforms.api import transform from transforms.api import Output, Input, TransformContext, transform_pandas from transforms.external.systems import external_systems, Source, ResolvedSource import pandas as pd import logging logger = logging.getLogger(__name__) @external_systems( dictionary_api_source=Source( "<source_rid>" ) ) @transform_pandas( Output("<output_dataset_rid>"), words_df=Input("<input_dataset_rid>"), ) def compute(dictionary_api_source: ResolvedSource, words_df: DataFrame) -> DataFrame: dictionary_api_url = dictionary_api_source.get_https_connection().url dictionary_api_client = dictionary_api_source.get_https_connection().get_client() words = words_df["word"].tolist() phonetics= [] for word in words: logger.info("Fetching word from api.dictionaryapi.dev: " + word) response = dictionary_api_client.get( dictionary_api_url + "/api/v2/entries/en/" + word ) if response.status_code == 200: data = response.json()[0] if "phonetic" in data: phonetic_transcription = data["phonetic"] else: logger.warning(f"No phonetic transcription found for {word}.") phonetic_transcription = None else: logger.warning(f"Request for {words} failed with status code {response.status_code}.") phonetic_transcription = None phonetics += [{"word": word, "phonetic": phonetic_transcription}] return pd.DataFrame(phonetics)
一般的なシステムを対象とした複雑なエンドツーエンドの例については、以下のドキュメントを参照してください。
外部トランスフォームを使用する前に、Data Connection - 権限リファレンスページの内容を確認してください。
lightweight 外部トランスフォーム外部トランスフォームは、シングルノード(軽量)のコンピュートエンジンにも対応しています。軽量コンピュートを使用すると、小規模および中規模のデータを処理するトランスフォームの実行速度を大幅に向上できます。
次の例は、@external_systems デコレーターとともに @lightweight デコレーターをトランスフォームに追加する方法を示しています。軽量トランスフォームの設定オプションの詳細については、Python トランスフォームのドキュメントを参照してください。
Copied!1 2 3 4@lightweight @external_systems( dictionary_api_source=Source("<source_rid>") )
より詳細な例については、Python でのソースの使用を参照してください。
外部トランスフォームは、Agent プロキシポリシーを使用して、Data Connection の Agent 経由でオンプレミスおよびプライベートにホストされたシステムに接続できます。
次の例は、Spark サイドカートランスフォームを使用して PostgreSQL データベースに接続する方法を示しています。詳細については、Spark サイドカートランスフォームのドキュメントを参照してください。
次の例よりも単純なユースケースでは、Spark サイドカートランスフォームが不要な場合があります。Spark サイドカートランスフォームを必要としないほかの例は、このページの別のセクションにあります。
プライベートネットワークにアクセスできるように外部トランスフォームを設定するには、次の手順を実行します。
3. コードのインポートを有効化: コードのインポート設定パネルで、このソースを Code Repositories にインポートできるようにするをオンにします。
4. トランスフォームのコードリポジトリをセットアップし、ソースをインポートします。
この例は、サイドカーコンテナ内のコンテナ化された Flask API を使用して PostgreSQL データベースにクエリを実行する方法を示しています。
Copied!1 2 3 4 5 6 7 8FROM python:3.8-slim WORKDIR /usr/src/app COPY requirements.txt ./ RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 1234 USER 5001 CMD ["python", "app.py"]
flask
psycopg2-binary
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 31from flask import Flask, jsonify import psycopg2 app = Flask(__name__) @app.route('/tables', methods=['POST']) def tables(): data = request.get_json() password = data.get('password') connection_params = { "dbname": "<databasename>", "user": "<user>", "password": password, "host": "postgres.com", "port": "5432", } data = {"schema": [], "table": []} with psycopg2.connect(**connection_params) as conn: with conn.cursor() as cur: cur.execute( "SELECT table_schema, table_name FROM information_schema.tables WHERE table_type = 'BASE TABLE'" ) tables = cur.fetchall() for schema, table in tables: data["schema"].append(schema) data["table"].append(table) return jsonify(data)
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18import requests from transforms.sidecar import sidecar from transforms.external.systems import external_systems, Source from transforms.api import transform_df, Output @external_systems( my_source=Source("<source_rid>") ) @sidecar(image="simple", tag="0.0.1") @transform_df( Output("<output_dataset_rid>"), ) def compute(my_source, ctx): password = my_source.get_secret("PASSWORD") response = requests.post("http://localhost:1234/tables", json={"password": password}) data = [(response.text,)] columns = ["table_schema_json"] return ctx.spark_session.createDataFrame(data, columns)
外部トランスフォームで外部ソースから大量のレコードを取得する場合、書き込む前にすべてのレコードをメモリーに保持すると、メモリー不足エラーが発生する可能性があります。次の BufferedParquetWriter クラスは、設定可能なメモリーしきい値を超えると、蓄積された行を Parquet ファイルに定期的にフラッシュします。このパターンは任意の外部データソースで使用でき、filesystem().open() を使用して生のファイルを書き込み、put_metadata() を使用してスキーマ推論を完了します。
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 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95import gc import logging from datetime import datetime import pyarrow as pa import pyarrow.parquet as pq from pympler import asizeof from transforms.api import Output, transform, LightweightOutput from transforms.external.systems import external_systems, Source, ResolvedSource logger = logging.getLogger(__name__) class BufferedParquetWriter: """行をメモリー内にバッファリングし、バッファーが 設定可能なサイズのしきい値を超えると Parquet ファイルに書き出します。""" def __init__(self, output: LightweightOutput, schema: pa.Schema, flush_threshold_mb: int = 64): self.output = output self.schema = schema self.flush_threshold_bytes = flush_threshold_mb * 1024 * 1024 self.buffer = [] self.buffer_size_bytes = 0 self.file_index = 0 self.row_size_estimate = None def append(self, row: dict): """バッファーに行を追加します。バッファーがしきい値を超えると、ディスクに書き出します。""" self.buffer.append(row) # 最初の行から行のサイズを推定し、以降はその推定値を使用します if self.row_size_estimate is None: self.row_size_estimate = asizeof.asizeof(row) self.buffer_size_bytes += self.row_size_estimate if self.buffer_size_bytes >= self.flush_threshold_bytes: self.flush() def flush(self): """バッファリングされた行を Parquet ファイルに書き込み、バッファーをクリアします。""" if not self.buffer: return self.file_index += 1 table = pa.Table.from_pylist(self.buffer, schema=self.schema) timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") filename = f"output_{timestamp}_{self.file_index}.parquet" with self.output.filesystem().open(filename, "wb") as f: pq.write_table(table, f) logger.info(f"Flushed {len(self.buffer)} rows to {filename}") self.buffer = [] self.buffer_size_bytes = 0 gc.collect() def finalize(self): """残っている行をすべて書き出し、スキーマ推論を開始します。""" self.flush() if self.file_index > 0: self.output.put_metadata() # 出力レコードのスキーマを定義します OUTPUT_SCHEMA = pa.schema([ ("id", pa.string()), ("name", pa.string()), ("value", pa.float64()), ]) @external_systems( my_source=Source("<source_rid>") ) @transform.using( output=Output("<output_dataset_rid>"), ).with_resources( memory_gb=4, ) def compute(my_source: ResolvedSource, output: LightweightOutput): output.set_mode("replace") writer = BufferedParquetWriter(output, OUTPUT_SCHEMA, flush_threshold_mb=64) # 以下のループをデータ取得ロジックに置き換えます。 # たとえば、API のページ、データベースカーソルの行、 # またはメッセージキューのメッセージを反復処理します。 # append() を呼び出すたびにライターにデータが追加され、バッファーが # しきい値を超えると、自動的に Parquet ファイルに書き出されます。 for record in fetch_records_from_source(my_source): writer.append({ "id": record["id"], "name": record["name"], "value": record["value"], }) # バッファーに残っている行をすべて書き込み、スキーマ推論を完了します。 writer.finalize()
たとえば CSV 形式を想定する外部システムにファイルを渡すために、Foundry からデータを CSV としてエクスポートする必要がある場合は、入力データセットを読み取り、filesystem().open() を使用して出力に CSV ファイルを書き込む外部トランスフォームを使用できます。その後、出力データセットを Data Connection 経由でエクスポートできます。
Copied!1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22import csv from transforms.api import Input, Output, transform, LightweightInput, LightweightOutput @transform.using( source_data=Input("<input_dataset_rid>"), csv_output=Output("<output_dataset_rid>"), ) def compute(source_data: LightweightInput, csv_output: LightweightOutput): OUTPUT_FILENAME = "export.csv" # 入力データセットを Polars DataFrame として読み込みます。 df = source_data.polars() fieldnames = df.columns # データを CSV ファイルとして書き込みます。 with csv_output.filesystem().open(OUTPUT_FILENAME, "w") as f: writer = csv.DictWriter(f, fieldnames=fieldnames) writer.writeheader() for row in df.iter_rows(named=True): writer.writerow(row)
レガシー外部トランスフォームは、Python トランスフォームから外部システムに接続するための従来の方法です。レガシー外部トランスフォームは @use_external_systems() を使用し、エグレスポリシーと資格情報をコードリポジトリに直接インポートします。このページで説明するソースベースの外部トランスフォームを、代替手段として推奨します。
レガシー外部トランスフォームとソースベースの外部トランスフォームのワークフローにおける主な違いは、次のとおりです。
@use_external_systems() デコレーターを使用します。ソースベースの外部トランスフォームは @external_systems() を使用します。ソースベースの外部トランスフォームの主な利点は、次のとおりです。
現在、レガシー外部トランスフォームからソースベースの外部トランスフォームへの自動移行手段はありません。ただし、ほとんどのワークフローでは、必要な手動操作はわずかで済むと見込まれます。
レガシー外部トランスフォームをソースベースの外部トランスフォームに手動で移行するには、次のステップに沿って進めます。
@external_systems() デコレーターをインポートし、ソースへの参照を指定して使用するようにコードを変更してから、レガシーの @use_external_systems() デコレーターをすべて削除します。その際、トランスフォームのロジック内にある資格情報への参照を、今回インポートするソースから取得した資格情報を参照するように更新する必要が生じる可能性があります。1つのトランスフォームで、レガシーの @use_external_systems() デコレーターとソースベースの @external_systems() デコレーターを両方使用することはできません。レガシー外部トランスフォームを @external_systems() を使用するように移行するか(推奨)、これらのデコレーターのいずれか1つだけを使用する個別のトランスフォームに分割してください。