Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
オントロジーの構築概要関数での外部ソース

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

関数での外部ソース

このガイドでは、webhookを使用して外部システムにリクエストを行う関数の設定方法について説明します。

前提条件

このガイドでは、事前にデータコネクションソースとWebhookを作成していることが前提となっています。詳しくは、データコネクションソースとWebhookの作成方法に関するドキュメントを参照してください。

関数リポジトリにソースをインポートする

このガイドに従う前に、関数リポジトリを作成し、関数の作成と公開方法を理解していることを確認してください。詳しくは、チュートリアルを参照してください。

関数でWebhookを使用するには、まずWebhookの背後にあるREST APIソースをリポジトリにインポートする必要があります。画面左側のリソースインポートサイドパネルを選択して、リポジトリにインポートされたソースを表示します。追加 > ソースを選択すると、インポートしたいソースを選択できる検索ダイアログが表示されます。このダイアログでは、API名が付いているソースのみがインポート可能です。

特定のソースがインポート対象として選択されている外部関数ソースインポートモーダル

関数リポジトリへのソースインポートは、Python トランスフォームリポジトリや計算モジュールへのソースインポートとは異なります。特定のソースをインポートする関数リポジトリは、ソース概要に表示されるリポジトリのリストには表示されません。ソースに対して Viewer アクセス権を持つユーザーは、外部関数でそのWebhookをインポートして使用することができます。

関数でのWebhooksの使用

REST APIソースをFunctionsリポジトリにインポートすると、TypeScript環境で利用可能になり、ソースの名前空間を介してアクセスできます。 エラー Cannot find module '@foundry/external-systems' or its corresponding type declarations. が表示された場合、functions-typescript/functions.json ファイル内で enableExternalSystems の値が true に設定されていることを確認してください。これを更新し、変更をコミットすると、システムは必要なパッケージをインストールします。これには @foundry/external-systems も含まれます。

External Functions import error message.

例：関数から複数のコールを行う

以下の例では、単一の関数を使用して辞書APIへの複数のコールを行う方法を説明します。

関数がオントロジーの編集を行わない場合、@Query() 関数を作成します。オントロジーの編集を行いたい場合は、代わりに @OntologyEditFunction デコレーターが必要となります。関数からオントロジーの編集を行う方法の詳細については、ドキュメンテーションをご覧ください。

標準の TypeScript async/await パターン ↗ を使用すると、関数から複数のWebhookコールを同時に行うことができます。@foundry/functions-api からエクスポートされた isOk ヘルパー関数を使用してコールの成功を確認します。

次の関数は、TypeScriptの文字列配列として単語のリストを受け入れ、各単語に対して1つのコールを行います： ["tuba", "cool"] の入力に対するログ出力：

LOG [2023-07-28T03:16:22.968Z] "チューバ"の名詞定義が見つかりました：大きな金属製の楽器で、通常は低音域で演奏され、口pieceに対する唇の振動とキーの押下によって音が出ます。
LOG [2023-07-28T03:16:22.968Z] "チューバ"の名詞定義が見つかりました：ローマ軍のトランペットの一種で、現代のチューバとは異なります。
LOG [2023-07-28T03:16:22.968Z] "チューバ"の名詞定義が見つかりました：オルガンの大きなリードストップ。
LOG [2023-07-28T03:16:22.968Z] "チューバ"の名詞定義が見つかりました：その根がロテノンの重要な供給源であるマレーシアの植物、Derris malaccensis。
LOG [2023-07-28T03:16:22.968Z] "チューバ"の名詞定義が見つかりました：ココナッツやニッパ樹液から作られた赤いパームワイン。
LOG [2023-07-28T03:16:22.968Z] "チューバ"の名詞定義が見つかりました：管または管状の器官。
LOG [2023-07-28T03:16:22.968Z] "クール"の名詞定義が見つかりました：適度なまたは爽快な寒さ状態；暑いと冷たいの間の空気の適度な温度；涼しさ。
LOG [2023-07-28T03:16:22.968Z] "クール"の名詞定義が見つかりました：落ち着いた気質。

エラーハンドリング

ネットワーク化されたシステムで作業する際の失敗を軽減するために、関数は Result オブジェクトを使用して Webhook から伝播されるエラーを公開します。これにより、発生したエラーの種類に関する情報が提供されます： エラー処理時には、作成したコードが特定の名前をリッスンし、それに応じて反応する必要があります。現在、Functions は以下のエラーを返します：

エラー説明
WebhookExecutionFailedToStartWebhook の開始に失敗しました。このエラーが返された場合、外部システムへのリクエストは一切行われなかったと安全に想定できます。
WebhookExecutionTimedOutWebhook の実行が開始されましたが、設定されたWebhookのタイムアウト時間内に外部システムからの応答が受け取られませんでした。
RemoteRestApiReturnedError外部システムがエラーを返しました。REST API ソースに設定された Webhook のみで返されます。
RemoteApiReturnedError外部システムがエラーを返しました。REST API以外のソースに設定されたWebhookのみで返されます。
ParsingResponseFailedWebhook の実行は成功しましたが、外部システムからの応答を正常に解析できませんでした。たとえば、外部システムからの応答が期待されるフィールドを含まない場合などに発生します。Webhook の呼び出し結果は必ずしも使用されるわけではないため、これをユーザーに対する失敗とするかどうかはアプリケーションビルダーの判断に委ねられます。
ServerErrorWebhook サービスまたはコネクタ内部で問題が発生しました。
UnknownErrorFoundry サービスに直接関連付けられないエラーが発生しました。

このエラータイプのリストは変更される可能性があります。ユーザーは、Function 実行者が新しい名前のエラーを返す場合に備えて、コードにデフォルトケースを含めるように構造化する必要があります。

例：単一の Function から複数の webhook 呼び出しを行い、エラーを処理する

以下のコードは、同じ function 内で一部が成功し、一部が失敗する複数の webhook 呼び出しをどのように処理するかを説明しています。私たちの例では、辞書サーバーが指定された単語の定義を見つけられない場合、RemoteRestApiReturnedError が返されます。 上記の関数に ["asdf", "shire"] を入力すると、次の結果が返されます：

LOG [2023-07-28T15:38:47.263Z] ERROR: asdfは定義できませんでした リクエストは失敗のレスポンスコードを返しました: 404 レスポンス本文: {"title":"定義が見つかりません","message":"申し訳ありませんが、お探しの単語の定義を見つけることができませんでした。","resolution":"後で再度検索を試すか、ウェブに移動してみてください。"}
# asdfが定義できなかったというエラーログ。レスポンスコード404を返しました。サーバーからのレスポンスでは定義が見つからないというメッセージが返ってきています。

LOG [2023-07-28T15:38:47.264Z] Found a noun definition for "shire": Physical area administered by a sheriff.
# "shire"という名詞の定義を見つけました：シェリフによって管理される物理的なエリア。

LOG [2023-07-28T15:38:47.264Z] Found a noun definition for "shire": Former administrative area of Britain; a county.
# "shire"という名詞の定義を見つけました：イギリスの旧行政区域；郡。

LOG [2023-07-28T15:38:47.264Z] Found a noun definition for "shire": The general area in which a person lives or comes from, used in the context of travel within the United Kingdom.
# "shire"という名詞の定義を見つけました：一般的に、人が住んでいるか出身のエリア。イギリス国内の旅行の文脈で使用されます。

LOG [2023-07-28T15:38:47.264Z] Found a noun definition for "shire": A rural or outer suburban local government area of Australia.
# "shire"という名詞の定義を見つけました：オーストラリアの農村部や郊外の地方自治区域。

LOG [2023-07-28T15:38:47.264Z] Found a noun definition for "shire": A shire horse.
# "shire"という名詞の定義を見つけました：シャイア馬。

LOG [2023-07-28T15:38:47.264Z] Found a verb definition for "shire": To (re)constitute as one or more shires or counties.
# "shire"という動詞の定義を見つけました：1つ以上のシャイアまたは郡として（再）構成する。

制限事項

現在、オントロジー編集関数内から行うリクエストの数には制限がありませんが、既存の 関数リソース制限 は適用されます。また、Webhook制限 も適用されます。

関数は現在、以下の入力と出力タイプを持つwebhookをサポートしています：

  • 添付ファイル
  • ブール値
  • 整数
  • ロング
  • ダブル
  • 文字列
  • オプショナル
  • 日付
  • タイムスタンプ
  • リスト
  • 列挙型（許可される文字列型の値のリスト）
  • 期待されるフィールドのあるレコードとないレコード

@Query関数からwebhookを呼び出す際には、webhookは外部システムを変更しないRead API呼び出しのみを行う必要があります。クエリ関数は頻繁にリトライされるか、ページロード時に静かに実行されるため、@OntologyEditFunctionで可能な構造化された意図的な実行と同レベルのものを提供しません。webhookを設定する際には、Read APIまたはWrite APIのオプションを使用して、クエリ関数から安全に実行できるかどうかを指定できます。

サポートされていないwebhookの機能

  • 入力または出力パラメーターとしてOR型を使用するwebhookは現在サポートされていません。これらのwebhookのためのコードは生成されません。
  • アウトバウンドアプリケーションを通じてインタラクティブなOAuthを使用するREST APIソースで設定されたwebhookも現在サポートされていません。

関数とwebhookのバージョン変更を扱う

関数とwebhookにはバージョンがあり、呼び出し元は関数またはwebhookの任意のバージョンを呼び出すことができます。関数が公開されると、その時点で利用可能な最新のwebhookバージョンがそれにピン留めされます。

関数リポジトリがコードリポジトリアプリケーションで開かれると、オートコンプリートに使用される生成されたコードバインディングは常にwebhookの最新バージョンを使用します。このwebhookバージョンは、左側のリソースインポートサイドパネルに表示されます。

リソースインポートサイドパネルの関数リポジトリで、単一のwebhookを持つソースを示しています。

関数がその機能に依存する前に、webhookが安定していることを確認してください。

webhookまたは関数に変更が加えられたときには、関数を再公開し、ユーザーを新しいバージョンに移行することを忘れないでください。以前に公開されたピン留めされた関数のバージョンは、引き続き使用可能です。

権限

以下の表は、外部関数を作成、公開、利用するために必要な権限をまとめたものです。

アクションユーザー必要な権限
関数リポジトリにソースをインポートする関数エディタソースに対するsource:viewer権限。これはデフォルトのビューアロールに付与されます。
webhookを呼び出す関数を公開する関数エディタソースに対するwebhooks:execute権限。これはオーナーとエディターのデフォルトロールにのみ付与されます。
webhookを呼び出す@OntologyEditFunction()を使用してアクションを設定するアクションエディタwebhookに対するwebhooks:grant-action-validated-execution権限と関数に対するViewer権限
Workshopから@Query() webhookを実行するエンドユーザーソースに対するwebhooks:execute権限。これはOwnerとEditorのデフォルトロールにのみ付与されます。
アクションから@OntologyEditFunction()を実行するエンドユーザーユーザーはアクションの提出基準を満たす必要があります。この場合、ソース、webhook、または関数に対する権限はチェックされません。アクションを作成し管理するユーザーは、提出基準が適切に設定されていることを確認する必要があります。

監視、トラブルシューティング、デバッグ

以下のプラットフォームツールを使用して、関数からのwebhook実行についてより詳しい情報を得ることができます：

  • Webhook実行履歴は、Data Connectionで単一のwebhookを表示しているときに履歴タブで利用できます。
  • 関数の使用履歴は、Ontology Managerで利用でき、関数が実行された時間、入力、出力、関数をトリガーしたユーザーを含む履歴を表示します。
  • 関数のCode Authoringプレビューは、パフォーマンスプロファイリング、デバッグ出力などを提供します。

ベストプラクティス

関数からwebhookを呼び出すための外部ソースを使用する際には、以下のベストプラクティスを推奨します：

  • Data Connectionのtest webhook side panelでwebhookを徹底的にテストした後、関数でそれらのwebhookを使用しようと試みてください。
  • 可能であれば、期待されるフィールドを持つrecordタイプのパラメーターをwebhookの入力と出力で使用してください。JSONではなく、明示的な型を使用すると、関数コードが予期しないランタイムエラーをスローする可能性が低くなります。
  • 成功状態とエラー状態をチェックするために、@foundry/functions-apiからエクスポートされたisOkとisErrの組み込み関数を使用してください。エラーのタイプを名前フィールドを通じて絞り込みます。
  • ユーザーが一つの関数呼び出しで外部システムとオントロジーの両方に書き込む場合、オントロジーへの書き込みが失敗する可能性があることを覚えておいてください。これは、外部システムへの書き込みが成功した場合でも発生します。そのような不一致を処理する対策が適切に配置されていることを確認し、必要に応じてユーザーに両システムへの変更の状態を見る権限を与えてください。