注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
外部関数
外部関数を使用すると、関数から Webhook を呼び出し、それを使用して外部システムと対話することができます。これらのシステムは、 Workshop、Actions、そして Functions を使用して構築されたアプリケーションから呼び出すことができます。
関数でWebhookを使用するには、まず、Webhook機能をサポートする Data Connection source を設定する必要があります。通常、これは REST API source になります。Webhookが設定されたソースを持っている場合、そのソースを Functions repository にインポートし、Webhookやその他のロジックを呼び出す関数を作成することができます。
外部関数は、以下のような様々なユースケースに適用することができます：
- 単一の関数を使用して外部サーバーにHTTPリクエストを行い、レコードを作成し、その後、オントロジーに一致するレコードを書き込む。
- Webhook呼び出しをカスタムの前処理と後処理ロジックでラップする。これは、関数の入力から目的のWebhookリクエスト入力パラメーターへの変換にカスタムロジックが必要な場合、またはWebhookの応答に対してオントロジーの編集を行う前に後処理が必要な場合に特に有用です。
- 複数の外部Webhookリクエストとオントロジーの編集を、中間の処理ロジックで連鎖させる。単一のWebhookでは、外部リクエストの動的な数を実行することはできませんが、これは外部関数を使用して実現することができます。
- Workshopアプリケーションでデータを一時的にレンダリングするために、読み取り専用のリクエストを使用して外部システムをクエリする。
現在、TypeScriptコードから任意のAPI呼び出しを行うためには、まずそのリクエストをData ConnectionでWebhookとして定義する必要があります。
コンセプト
- Data Connection source は外部システムへの接続を表し、そのシステムに到達するための設定（例えば、ネットワーキングの詳細）や、安全に保存された資格情報を含みます。
- Webhooks は、いくつかのソースタイプがサポートする機能で、対話的に実行し、そのシステムにリクエストを送信するための構造化されたリクエストを作成することができます。
- Ontology edit Function は、後で Function-backed Action として設定し、オブジェクトに書き戻すことができる Function です。これは
@OntologyEditFunction()デコレーターで注釈付けされます。 - query Function は、読み取り専用の関数で、外部システムを変更するような副作用を持つことはできません。これは
@Query()デコレーターで注釈付けされます。
セットアップガイド
以下のセットアップガイドでは、無料の公開辞書API ↗ を呼び出すWebhookを作成する過程を説明します。すでにWebhookが設定された既存のソースがある場合は、関数からWebhookを呼び出すための external sources in functions に進んでください。
ここで説明されている辞書APIはPalantirとは関連しておらず、いつでも変更される可能性があります。このチュートリアルは、本APIを本番ユースケースで使用することを推奨、推薦、または提案するものではありません。
Data Connection sourceの作成
Functionsから外部システムに接続するためには、必要な外部APIに接続できるREST APIソースが必要です。以下の手順に従って新たなREST APIソースを設定します。
- Foundry内のData Connectionアプリケーションに移動し、New Source を選択します。オプションのリストから REST API を選択します。
-
Overview ページを確認した後、右下の Continue を選択します。次に、接続ランタイムを選択するよう求められます：直接接続、エージェントを介した接続、またはエージェントプロキシを介した接続。インターネット上で到達可能なものと対話する際には、直接接続が推奨されます。ここでは、私たちの無料の辞書APIに接続するためにそれを使用します。
-
ソースの名前を選び、それを保存するプロジェクトを選択します。
-
APIソースの接続情報を Domains セクションに記入します。以下に、私たちの無料の辞書APIの例での設定を示します：
- この例では、必要な出口ポリシーも作成する必要があります。前のステップを完了した場合、 Network Connectivity セクションで自動的にポリシーが提案されます：
- Save を選択し、ソース設定を完了するために Save and continue を選択します。このソースでWebhookを使用する設定をする前に、ソースの Overview ページに戻り、API名が設定されていることを確認します。この名前は、コード内でソースを参照するために必要です。
Data Connection sourceにWebhookを作成する
次に、前のステップで設定したREST APIソースにWebhookを設定する必要があります。その前に、関数からWebhookを呼び出すためには、Webhookを設定し、それにAPI名を割り当てる必要があります。Data Connectionソースには、複数のWebhookが関連付けられている場合があります。ソースのAPI名は名前空間内で一意であるべきであり、WebhookのAPI名はソース内で一意であるべきです。
以下の手順に従って、単語の定義をフェッチするために辞書APIにリクエストを行うWebhookを設定します。
- ソースの Overview ページで、Create webhook を選択します。Webhookに名前、説明、API名を付けます。APIソースと同様に、このWebhookはコード内で参照します。
- Webhookの実行時に渡すパラメーターを定義します。私たちの例では、単一の文字列入力パラメーター、
wordToDefineを使用します。
- 次に、URLに辞書のリソースパスを入力し、最後に入力パラメーターを参照するようにします。以下に示すように：
私たちは例では、APIはGETリクエストで、データを変更しません。したがって、Read API のデフォルト設定をそのままにします。これにより、Webhookは両方のタイプの関数、@Query() と @OntologyEditFunction() の両方で使用できます。Write API とマークされたWebhookは、@OntologyEditFunction() でのみ使用できます。
- 次のページでは、現在設定されているWebhookを実行するパネルが表示されます。Webhookを実行すると、未解析の応答が表示されます：
- Webhookでは、外部システムから返される応答オブジェクトを取得し、型付けされたスキーマに従ってフィールドを解析することができます。この例では、我々は各返された品詞に対する定義のリストを抽出します。一般的な単語（例えば "technology"）に対してWebhookを実行し、何か出力が返されることを確認します。
Webhookが保存されると、プラットフォーム全体で使用できます。
Webhookの設定オプションと使用法についてもっと学ぶ。.
次のステップ
このソースを関数で使用するためには、 external sources in functions のガイドに進んでください。