設定リファレンス

このページでは、Data Connection の Webhook に関連する詳細な設定オプションと権限について説明します。

入力と出力の設定

各 Webhook は、入力パラメーターを外部システムに送信するリクエストにマッピングするよう、柔軟に設定できます。その後、システムからのレスポンスを出力パラメーターとして取得し、Palantir Foundry の他の場所で使用できます。

入力パラメーター

入力パラメーターは、ユーザーが Webhook を実行するときに渡すことができる入力を表します。通常、Webhook はアクションタイプで使用するように設定します。アクションタイプでは、アクションパラメーターと Webhook の入力パラメーターの間のマッピングを指定できます。

Functions on Objects を使用してアクションパラメーターを Webhook の入力にマッピングする場合、入力をマッピングする関数が undefined を返すと、条件に応じて Webhook をまったく実行しないようにすることもできます。たとえば、WebhookInput | undefined です。

Webhook の入力パラメーターには、多くのデータ型と制約を利用できます。

• ブール値パラメーターには、true または false を指定できます。
• Integer、Long、Double パラメーターは数値を表します。
• 文字列パラメーターはテキスト値を表し、特定の値のみを許可するように制限できます。
• 日付パラメーターとタイムスタンプパラメーターは、時間に関するデータを表します。

これらの基本的なデータ型に加え、いくつかのコレクション型を利用できます。

• リストパラメーターは、特定のデータ型の入力を順序付きでまとめたものを表します。
• 記録パラメーターでは、キーと値のペアを渡すことができ、特定のデータ型の値を持つ特定のキーを必須にするように制限できます。
• 任意パラメーターは、存在する場合と存在しない場合がある入力を表します。

最後に、添付ファイルデータ型を使用すると、アクションフォームでアップロードされたファイルを渡すことができます。ただし、Agent ワーカーのソースでは利用できません。

出力パラメーター

出力パラメーターを使用すると、外部システムから返されたデータを取得し、Foundry の他の場所で使用できます。たとえば、外部システムで新しいレコードを作成すると、そのシステムは新しいレコードの ID を返すことがあります。この新しい ID を出力パラメーターで取得すると、アクションに伝播させ、すぐに Foundry オブジェクトに書き込むことができます。

Webhook のセットアップウィザードで、unique_id という名前の 1 個の出力パラメーターを設定する例を以下に示します。

また、Webhook の設定ステップで出力パラメーターに直接アクセスすることもできます。以下の例では、Webhook 呼び出しが前の呼び出しのレスポンスの値を使用します。最初の Webhook 呼び出しは、次のようなレスポンスを返します。

{
  "results": {
    "unique_id": "ID4567"
  }
}

2 番目の Webhook 呼び出しを設定します。ヘッダータブで @ を入力すると、前の呼び出しのレスポンスの値を参照できるメニューが開き、インライン参照を作成できます。

呼び出しからを選択し、パースするレスポンスを持つ前の呼び出しを選択します。レスポンスから必要な値を抽出するには、3 個の選択肢があります。

• **レスポンス全体：**レスポンス全体を文字列として抽出します。
• **キーで抽出：**レスポンス内のキーを使用して、必要な値を抽出します。
• **インデックスで抽出：**インデックス位置（0 始まり）を使用して、配列のレスポンスから必要な値を抽出します。

以下の例のように、キーで抽出を選択し、ネストされたキーを追加オプションを使用して、results、続いて unique_id の順にキーを設定します。

追加を選択すると、ヘッダー値のフィールドに参照が表示されます。

取得される出力パラメーターは、使用しているタスクの種類によって異なります。

REST Webhook から出力パラメーターを取得し、アクションで使用する方法について、詳しくはこちら。

利便性のため、特定の場合には Webhook タスクの結果が適切な出力パラメーターのデータ型に自動的に変換されます。

• 文字列の出力パラメーターが設定されており、Webhook タスクの結果が文字列ではない場合、結果は JSON 文字列に変換されます。
• 記録の出力パラメーターが設定されており、Webhook タスクの結果が文字列の場合、Webhook サービスはその文字列を JSON としてパースしようとします。
• Double の出力パラメーターが設定されている場合、Integer または Long の Webhook タスクの結果は自動的に変換されます。

出力パラメーターは、「接続をテスト」サイドパネルから送信したリクエストのレスポンスを使用して設定できます。テストリクエストに成功すると、新しい出力パラメーターを追加する際に、レスポンスからパースされた出力候補が自動的に表示されます。

タスク本文

一部の Webhook はタスクとして実装されています。これらの Webhook では、タスク本文は Webhook の実行時にタスクに送信されるデータを表します。

各タスクが期待する構造は、タスクの種類によって異なります。該当する場合は、Webhook の種類の項目に記載されています。タスク本文は、Handlebars ↗ 構文を使用して定義する必要があります。タスク本文では、上記で説明したように、Webhook に定義した任意の入力パラメーターを参照できます。

Webhook の種類

Webhook の各種類は、異なる設定オプションに対応しています。このセクションでは、さまざまな種類の Webhook で利用可能なオプションについて説明し、利用をはじめるための基本的な例を示します。

REST API

Webhook の最も一般的な用途は、REST API に HTTP リクエストを送信することです。REST API ソースを設定した後、リクエストビルダーのインターフェースを使用して、送信するリクエストを作成できます。

REST API ソースで利用可能なオプションは次のとおりです。

複数のリクエスト

1 個の Webhook に複数のリクエストを含めることができます。リクエストを連結して、前の呼び出しのレスポンス値を後続の呼び出しで参照できます。

REST API（レガシー）

magritte-rest-v2 ソースをセットアップした後、generic-rest-webhook-task を使用して REST Webhook を作成できます。

REST Webhook のタスク本文の構造は、calls の配列にする必要があります。各要素は、外部システムに送信する REST リクエストを表します。Webhook で利用可能な call の種類は、magritte-rest-call のみです。

以下は、1 回の HTTP 呼び出しを表す、REST Webhook の基本的なタスク本文テンプレートの例です。

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
    "calls": [
        {
            "type": "magritte-rest-call",
            "method": "POST",
            "requestMimeType": "application/json",
            "path": "your/request/path",
            "body": { "text": {{json message}} }
        }
    ]
}

このタスク本文テンプレートは、your/request/path エンドポイントに、リクエスト本文 { text: <message> } を持つ POST リクエストを送信します。ここで、<message> は Webhook の文字列入力パラメーターです。

出力パラメーターの抽出

REST Webhook から出力パラメーターを抽出するには、主に 2 個の方法があります。1) JSON レスポンスの最上位フィールドを名前で取得する方法、2) より細かくカスタマイズした抽出ロジック用の JSON エクストラクターを定義し、出力するフィールドを明示的に列挙する方法です。

レスポンス JSON 全体を文字列出力として抽出することもできます。これにより、関数を使用して後続の編集や通知の表示を行う際に、レスポンスを柔軟にたどることができます。

最上位フィールドを取得する場合、次のレスポンスを返す REST 呼び出しを設定したとします。

Copied!
1
2
3
{
    "id": "c52fd6e4-6eb5-4da1-8908-4845e51c801b"
}

JSON レスポンス内のキーと同じ ID を持つ出力パラメーターを定義することで、それらを取得できます。この例では、パラメーターIDが id の文字列出力パラメーターを追加すると、このフィールドがレスポンスから取得されます。

レスポンスからネストされたフィールドを取得する必要がある場合は、extractors を指定して値を抽出できます。抽出した値は、後続の呼び出しで使用して、呼び出しを連結することもできます。レスポンス全体を取得する必要がある場合は、ルートパスを対象とする extractors、つまり "result": "/" を指定して、レスポンス全体を抽出できます。

以下は、2 個のリクエストを送信するタスク本文テンプレートの例です。最初に GET エンドポイントからデータを取得し、次に前の呼び出しのデータを使用して POST エンドポイントにリクエストを送信します。

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
{
    "calls": [
        {
            "type": "magritte-rest-call",
            "method": "GET",
            "path": "path/to/fetchData",
            "extractor": [
              {
                "type": "json",
                "assign": {
                  "request_output": "/json/path/to/output"
                }
              }
            ]
        },
        {
            "type": "magritte-rest-call",
            "method": "POST",
            "path": "your/request/path",
            "body": { "text": {%request_output%} },
            "extractor": [
              {
                "type": "json",
                "assign": {
                  "result": "/json/path/to/result"
                }
              }
            ]
        }
    ],
    "output": ["result"]
}

最初の呼び出しは、path/to/fetchData のエンドポイントに GET リクエストを送信し、JSON パス /json/path/to/output からデータを抽出して、request_output という名前の状態変数に格納します。次に、request_output の状態が 2 番目の呼び出しの本文で使用されます。2 番目の呼び出しでは、JSON レスポンスから別のフィールドを抽出して、result という名前の状態変数に格納します。最後に、設定内の "output" フィールドで、抽出したどのフィールドを出力パラメーターとして返すかを定義します。

その他のオプション

REST Webhook タスクでは、calls と output の指定に加え、いくつかの追加設定オプションを利用できます。

• REST Webhook で複数の呼び出しを行う場合、安全でない HTTP メソッドを使用できる呼び出しは 1 回のみです。安全でない呼び出しとは、外部システムの状態を変更する可能性がある呼び出しです。デフォルトでは、GET、OPTIONS、HEAD リクエストのみが安全と見なされます。呼び出しのフィールドとして "isHttpMethodSafe": true を指定すると、別の種類の呼び出し（POST や PUT など）の安全性の判定をオーバーライドできます。これは、複数のリクエストを送信し、前半のリクエストの 1 個が POST で、そのレスポンスを後続のリクエストで使用する場合に役立ちます。
• 再試行可能な HTTP ステータスコードを表す retryable-status-codes の配列を指定できます。
  • たとえば、サーバーから 503 レスポンスを受信したときに、外部リクエストを再試行するよう Webhook を設定できます。このオプションのデフォルトは空のリストです。
• リクエストに失敗しても接続先サーバーのデータが変更されなかったことを示す external-system-not-changed-status-codes の配列を指定できます。
  • このオプションのデフォルトは、400 から 431 までのすべてのステータスコードです。
  • Webhook を実行して失敗した場合、書き込み失敗のデバッグができるように、外部システムが変更された可能性があるかどうかを示す情報が記録されます。

Salesforce

Salesforce Webhook では、次の種類のタスクを利用できます。

• create-record-salesforce-webhook-task：指定した種類の Salesforce レコードを作成します。
• update-record-salesforce-webhook-task：指定した種類の Salesforce レコードを更新します。
• delete-record-salesforce-webhook-task：Salesforce レコードを削除します。
• composite-salesforce-webhook-task：Salesforce の複合リクエスト ↗を使用して、Salesforce レコードを変更します。

以下に、各タスクの種類のタスク本文の例を示します。

create-record-salesforce-webhook-task

この種類のタスクは、こちらの Salesforce API ↗ に対応します。

Copied!
1
2
3
4
5
6
7
8
{
  "record-type-name": "Account",
  "data": {
    "Name": {{json name}},
    "Industry": {{json industry}},
    "BillingCountry": {{json country}}
  }
}

update-record-salesforce-webhook-task

この種類のタスクは、こちらの Salesforce API ↗ に対応します。

Copied!
1
2
3
4
5
6
7
8
9
{
  "record-type-name": "Account",
  "record-id": {{json record-id}},
  "data": {
    "Name": {{json name}},
    "Industry": {{json industry}},
    "BillingCountry": {{json country}}
  }
}

delete-record-salesforce-webhook-task

この種類のタスクは、こちらの Salesforce API ↗ に対応します。

Copied!
1
2
3
4
{
  "record-type-name": "Account",
  "record-id": {{json record-id}}
}

composite-salesforce-webhook-task

collateSubrequests オプションの詳細は、Salesforce ドキュメント ↗を参照してください。

以下の例では、"@{createAccount.id}" を使用して、最初のサブリクエストで作成したレコードの ID を参照します。依存関係のあるリクエストについては、Salesforce ドキュメント ↗を参照してください。

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
{
  "request": {
    "collateSubrequests": true,
    "compositeRequest": {
      "createAccount": {
        "type": "createRecord",
        "createRecord": {
          "recordTypeName": "Account",
          "data": {
            "Name": {{json name}}
          }
        }
      },
      "updateId": {
        "type": "updateRecord",
        "updateRecord": {
          "recordTypeName": "Account",
          "data": {
            "Industry": {{json industry}}
          },
          "recordId": "@{createAccount.id}"
        }
      }
    }
  }
}

SAP

SAP 固有の Webhook 設定については、SAP ERP コネクターのドキュメントの Webhook セクションを参照してください。カスタム YAML ベースのソースを使用するレガシー統合については、SAP（カスタムソース）を参照してください。SAP Webhook は、Foundry が管理するクラウドコンピュート内の Foundry ワーカーで実行することを推奨します。

制限

各 Webhook には、実行方法を制約する 3 種類の制限を設定できます。時間制限、同時実行制限、レート制限です。

時間制限では、Webhook の最大実行時間を設定できます。これにより、エンドユーザーのアプリケーションの応答性を維持し、接続先の外部システムの応答に時間がかかりすぎている場合にタイムアウトエラーを表示できます。値を指定しない場合、デフォルトのタイムアウトは 20 秒です。許容されるタイムアウトの最大値は 180 秒です。

同時実行制限では、同時に実行する Webhook の最大数を指定します。これを定義することで、同時リクエストが多すぎて外部システムに過負荷がかかることを防止できます。

レート制限では、指定した時間枠内で Webhook を実行できる回数を制限します。Webhook の実行回数を毎秒、毎分、毎時、または毎日、特定の回数以内に抑えることを保証したい場合は、この種類の制限を有効にできます。

Webhook 関数

Webhook を関数として公開すると、他のアプリケーションで再利用可能な関数になります。公開するには、Webhook を作成するときに関数の設定のトグルをオンのままにするか、既存の Webhook の関数の設定セクションから直接公開します。関数の公開を有効にした後に作成されるすべての Webhook バージョンは、関数のバージョンとしても公開されます。この操作は取り消せず、Webhook から公開した関数は削除できません。

Webhook 関数は、他のオントロジー関数と同じ場所から呼び出すことができます。

• Workshop モジュール
• TypeScript v2 関数と Python 関数
• オントロジー SDK（OSDK）
• 関数を利用したアクション
• Machinery と Automate

TypeScript v2 または Python 関数で Webhook を使用するには、まず関数として公開する必要があります。公開した関数を関数リポジトリにインポートし、オントロジー SDK を使用して呼び出します。

権限

Webhook の作成、設定、削除の権限は、関連付けられたソースの権限から派生します。

Data Connection の権限および Webhook の権限の詳細について、詳しくはこちらをご覧ください。

Webhook の履歴

Webhook の履歴には、Webhook が実行された時点を示すタイムラインが表示されます。以下に示すように、履歴のメタデータには常に、Webhook を実行したユーザーID、タイムスタンプ、実行の成功または失敗のステータスが含まれます。

デフォルトでは、Webhook に渡された入力とレスポンス全体は、Webhook を呼び出したユーザーのみが閲覧できます。これにより、Webhook 呼び出しに渡された、または呼び出しから返された機密データが保護されます。webhooks:read-privileged-data 権限があると履歴全体にアクセスできますが、デフォルトではどのユーザーにも付与されていません。Webhook の履歴全体にアクセスするには、この権限を持つカスタムロールが必要です。

その他のオプション

レスポンスの保存

デフォルトでは、Webhook のレスポンスは 6 か月間保存され、履歴表示に表示されます。レスポンス全体を閲覧できるのは、Webhook を実行したユーザーと、webhooks:read-privileged-data 権限を持つ管理者のみです。

Webhook の履歴に保存すべきでない機密情報を返すことがわかっている Webhook では、このオプションを完全に無効にできます。

Webhook での OAuth 2.0

認可コードグラント

Palantir Webhook は、OAuth 2.0 認可コードグラントフローを使用したエンドポイントの呼び出しに対応しています。これには、アウトバウンドアプリケーションを使用して、OAuth 2.0 サーバーとのインタラクションを定義する必要があります。設定後、アウトバウンドアプリケーションは REST API Webhook の認証として使用できます。ユーザーが Webhook を実行しようとすると、OAuth サーバーで認証するためのダイアログが各ユーザーに表示されます。

認可コードグラントのトラブルシューティング

認可コードグラントを使用するアウトバウンドアプリケーションでエラーが発生した場合は、次の一般的な問題を確認してください。

「クライアントには認可コードをリクエストする権限がありません」

このエラーは、サードパーティアプリケーションが認可コードフローを使用するように設定されていないことを示します。Developer Console で、サードパーティアプリケーションの認可コードグラントが有効になっていることを確認してください。

「指定されたリダイレクト URI は、許可されたリダイレクト URI ではありません」

このエラーは、認可コードグラントの設定で指定されたリダイレクト URI が、アウトバウンドアプリケーションの期待するリダイレクト URI と一致しない場合に発生します。認可コードグラントの設定で、リダイレクト URL をアウトバウンドアプリケーションのリダイレクトページ URL と完全に一致するように設定してください。

https://<your-enrollment>.palantirfoundry.com/workspace/oauth2-clients/callback

認可コードグラントのブロック内のリダイレクト URL が、アウトバウンドアプリケーションのリダイレクトページ URL と一致すると、認可コードのリクエストに成功します。

クライアント資格情報グラント

Webhook を使用して、クライアント資格情報による OAuth フローを実行できます。クライアント資格情報グラントフローでは、通常、有効期間の長いシークレットを使用して、有効期間の短いアクセストークンを取得し、ターゲットシステムに対するアクションを実行します。REST API Webhook は、複数の API 呼び出しを順番に連結することに対応しており、クライアント資格情報のハンドシェイクと、その後の目的のリクエストを 1 回の実行で行うことができます。

以下のウォークスルーでは、仮想的なサンプルシステムに対するクライアント資格情報グラントフローの設定方法を説明します。

続行するには、次の情報が必要です。

• OAuth 2.0 サーバードメインとトークンエンドポイントへのパス。トークンエンドポイントは、リソースドメインにリクエストを送信するための有効なトークンの取得に使用します。
  • 多くの場合、OAuth 2.0 サーバードメインとリソースドメインは同じです。たとえば、Foundry API でサードパーティアプリケーションを使用して認証する場合がこれに該当します。
• リソースドメインと、呼び出したいエンドポイントへのパス。呼び出しには、OAuth 2.0 サーバーから取得した Bearer トークンを含む Authorization ヘッダーを使用します。
• OAuth 2.0 サーバーのクライアントID。
• OAuth 2.0 サーバーのクライアントシークレット。

REST API ソースの作成

まず、Data Connection アプリケーションで + 新規ソースの作成を選択し、ソースの種類として REST API を選択します。REST API ソースの種類について、詳しくはこちらをご覧ください。

ソースを設定するときに、以下に示すように、OAuth 2.0 サーバードメインとリソースドメインの両方を追加します。認証オプションは選択しないでください。Webhook 呼び出しのシーケンス内で、OAuth 2.0 ハンドシェイクを直接、手動で実行するためです。

追加の秘密セクションで、新しいシークレットを追加し、トークンエンドポイントへのリクエスト時に含める ClientSecret を入力します。この値は Webhook 呼び出しの作成時に参照します。ここで入力した ClientSecret は暗号化され、Foundry 内でそのソースの他の編集者や所有者にも公開されません。

クライアント資格情報のハンドシェイクを実行する Webhook の作成

ソースを作成したら、新しい Webhook を作成するオプションを選択します。

Webhook は、連結された 2 回の呼び出しで構成されます。

• 有効な Bearer トークンを取得するための、トークンエンドポイントへの最初の呼び出し
• パースされた Bearer トークンを含めて、リソースドメインの目的のエンドポイントにリクエストを送信する後続の呼び出し。

最初の呼び出しの設定例を以下に示します。

2 番目の呼び出しでは、利用可能な設定オプションを使用して、目的のリクエストを作成します。Bearer トークンを認可ヘッダーに挿入するには、呼び出し設定のヘッダーセクションに移動し、以下の例のようにヘッダーを追加します。@ を使用して、前の呼び出しの値を参照できます。ほとんどの OAuth 2.0 サーバーは、access_token などの名前の JSON パラメーターを返します。呼び出しから値を追加する選択肢を選び、次にキーで抽出を選択して、最初に行った呼び出しのレスポンスから抽出したいキーの値を入力します。

最初の呼び出しから Bearer トークンを選択する例を、以下のスクリーンショットに示します。

設定が完了すると、2 回の連結された呼び出しを持つ Webhook は、次の例のようになります。

最後に、Webhook の最初の呼び出しのレスポンス全体を保存しないようにすることを強く推奨します。レスポンスを保存すると、Webhook の履歴全体を閲覧する権限を持つ他のユーザーが、そのレスポンスに含まれる Bearer トークンを閲覧できる可能性があります。通常、Webhook 設定の保管と保持ページには、以下に示すように、トークンエンドポイントへのリクエストの履歴保存を無効にするよう促すプロンプトが自動的に表示されます。