Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
データ接続と統合データ接続コードからの外部接続外部関数

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

外部関数

外部関数を使用すると、Webhook を関数から呼び出し、外部システムとやり取りできます。これらのシステムは、Workshop、アクション、関数を使用して構築したアプリケーションから呼び出せます。

関数で Webhook を使用するには、まず Webhook 機能をサポートする Data Connection ソースを設定する必要があります。通常は REST API ソースを使用します。TypeScript v1 関数では、Webhook が設定されたソースを用意したら、そのソースを関数リポジトリにインポートし、Webhook の呼び出しやほかのロジックを実行する関数を作成できます。

ラッパーコードを記述せずに、Webhook を再利用可能なオントロジー関数として直接公開することもできます。TypeScript v2 または Python 関数で Webhook を使用するには、Webhook 関数として公開します。公開済みの関数を関数リポジトリにインポートし、オントロジー SDK を使用して呼び出します。

外部関数は、次のようなさまざまなユースケースに活用できます。

  • 1個の関数を使用して外部サーバーに HTTP リクエストを送信してレコードを作成し、その後、対応するレコードをオントロジーに書き込みます。
  • Webhook の呼び出しをカスタムの前処理および後処理ロジックでラップします。これは、関数の入力から目的の Webhook リクエストの入力パラメーターを生成するためにカスタムロジックが必要な場合や、オントロジーを編集する前に Webhook のレスポンスに対する後処理が必要な場合に、特に役立ちます。
  • 外部への Webhook リクエストとオントロジーの編集を、処理ロジックを挟んで連結します。1個の Webhook では、動的な数の外部リクエストを実行できませんが、外部関数を使用すれば実行できます。
  • 読み取り専用のリクエストを使用して外部システムにクエリを実行し、Workshop アプリケーションでデータを一時的に表示します。

現在、Data Connection でリクエストを Webhook として事前に定義しない限り、外部関数を使用して TypeScript コードから任意の API 呼び出しを行うことはできません。

概念

  • Data Connection ソースは、外部システムへの接続を表します。これには、そのシステムに接続する方法に関する設定（ネットワークの詳細など）や、安全に保存された資格情報が含まれます。
  • Webhook は、一部のソースタイプがサポートする機能です。構造化されたリクエストを作成し、対話的に実行して、そのシステムにリクエストを送信できます。
  • オントロジー編集関数は、後で関数ベースのアクションとして設定し、オブジェクトに書き戻せる関数です。@OntologyEditFunction() デコレーターでアノテーションを付けます。
  • クエリ関数は、外部システムの変更などの副次的効果を一切伴うことができない、読み取り専用の関数です。@Query() デコレーターでアノテーションを付けます。

セットアップガイド

このセットアップガイドでは、無料の公開辞書 API ↗ を呼び出す Webhook の作成手順を説明します。Webhook が設定されたソースがすでにある場合は、関数内の外部ソースに進み、関数から Webhook を呼び出す方法を確認してください。

ここで紹介する辞書 API は Palantir とは関係がなく、いつでも変更される可能性があります。このチュートリアルは、本番環境のユースケースでこの API を使用することを支持、推奨、または提案するものではありません。

Data Connection ソースを作成する

Functions から外部システムに接続するには、目的の外部 API に接続できる REST API ソースが必要です。以下の手順に沿って、新しい REST API ソースを設定できます。

  1. Foundry 内の Data Connection アプリケーションに移動し、新規ソースを選択します。選択肢の一覧から REST API を選択します。

REST API カードが赤枠で囲まれた Data Connection の新規ソースページ

  1. 概要ページを確認し、右下の続行を選択します。接続ランタイムを選択する画面が表示されます。Foundry ワーカー、Agent ワーカー、または Agent プロキシランタイム（サンセット）から選択します。Foundry のネットワークから直接アクセスできるものとやり取りする場合（直接接続エグレスポリシー経由）、または Foundry とは異なるネットワークでホストされているものとやり取りする場合（Agent プロキシエグレスポリシー経由）は、Foundry ワーカーを推奨します。 ここでは、直接接続ポリシーを使用する Foundry ワーカーで無料の辞書 API に接続します。

  2. ソースの名前を決め、保存先のプロジェクトを選択します。

  3. ドメインセクションに API ソースの接続情報を入力します。無料の辞書 API を使用するこの例の設定を以下に示します。

認証なしで api.dictionaryapi.dev に接続する設定を示す REST API ソース作成ページ

  1. この例では、必要なエグレスポリシーも作成する必要があります。前のステップを完了していれば、ネットワーク接続セクションにポリシーが自動的に提案されます。

ポート443の api.dictionaryapi.dev に対する推奨ポリシーを示すエグレス提案パネル

  1. 保存を選択し、次に保存および続行を選択してソースのセットアップを完了します。このソースで使用する Webhook を設定する前に、ソースの概要ページに戻り、API名が設定されていることを確認してください。この名前は、コード内でソースを参照するために必要です。

MyDictionarySource というAPI名を表示している、ソースのAPI名を設定するダイアログ

Data Connection ソースに Webhook を作成する

次に、前のステップで設定した REST API ソースに Webhook をセットアップする必要があります。また、関数から Webhook を呼び出すには、その前に Webhook を設定し、API名を割り当てる必要があります。Data Connection ソースには、複数の Webhook を関連付けることができます。ソースのAPI名は名前空間内で一意であるべきであり、Webhook のAPI名はソース内で一意である必要があります。

以下の手順に沿って、辞書 API にリクエストを送信して1つの単語の定義を取得する Webhook を設定します。

  1. ソースの概要ページで、Webhook を作成を選択します。Webhook に名前、説明、API名を設定します。API ソースと同様に、コード内で Webhook を参照します。

getDefinition という名前の Webhook を表示する新規 Webhook ページ

  1. Webhook の実行時に渡すパラメーターを定義します。この例では、文字列の入力パラメーター wordToDefine を1個使用します。

Data Connection の API ソース内にある Webhook 設定画面。

  1. 次に、以下に示すように、URL に辞書のリソースパスを入力し、末尾で入力パラメーターを参照します。

正しいデータを返すための入力パラメーターが追加された辞書 API のリソースパス。

この例では、API はデータを変更しない GET リクエストです。そのため、デフォルトの設定である読み取り API のままにして、Webhook を @Query() と @OntologyEditFunction() の両方の種類の関数で使用できるようにします。書き込み API に指定された Webhook は、@OntologyEditFunction() でのみ使用できます。

  1. 次のページには、現在の設定で Webhook を実行できるパネルが表示されます。Webhook を実行すると、パースされていないレスポンスが表示されます。

API ソースの Webhook のレスポンスのテスト。

  1. Webhook では、外部システムから返されたレスポンスオブジェクトを取得し、型付きスキーマに従ってフィールドをパースできます。この例では、返された品詞ごとに定義のリストを抽出します。Webhook を実行して、一般的な単語（たとえば「technology」）に対して何らかの出力が返されることを確認してください。

Webhook を保存すると、プラットフォーム全体で使用できるようになります。

Webhook の設定オプションと使用方法について詳しくはこちら。

次のステップ

このソースを関数で使い始めるには、関数内の外部ソースのガイドに進んでください。