設定リファレンス

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

入力と出力の設定

各 webhook は柔軟に設定でき、入力パラメーターを外部システムへのリクエストにマッピングします。その後、システムからの応答を出力パラメーターとしてキャプチャし、それらをPalantir Foundry の他の場所で使用できます。

入力パラメーター

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

Webhook 入力パラメーターには、多くのデータタイプと制約が利用可能です：

• ブーリアンパラメーターは true または false にすることができます。
• 整数、長整数、倍長整数パラメーターは数値を表します。
• 文字列パラメーターはテキスト値を表し、特定の値のみを許可するように制約することができます。
• 日付およびタイムスタンプパラメーターは時間ベースのデータを表します。

これらの基本的なタイプに加えて、いくつかのコレクションタイプが利用可能です：

• リストパラメーターは、特定のタイプの入力の順序付きコレクションを表します。
• レコードパラメーターはキー/値のペアを渡すことを可能にし、特定のキーを特定のタイプの値とともに必須にする制約を設けることができます。
• オプションパラメーターは、存在するかどうか不明な入力を表します。

最後に、添付ファイルタイプもあり、アクションフォームでアップロードされたファイルを渡すために使用できます。この機能は、ダイレクト接続またはエージェントプロキシソースでのみサポートされていることに注意してください。

出力パラメーター

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

単一の出力パラメーター unique_id の設定例を以下の Webhook 設定ウィザードで示します：

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

{
  "results": {
    "unique_id": "ID4567"  // ユニークID: これは各結果を一意に識別するためのIDです。
  }
}

2回目のWebhookコールを設定します。Headersタブで @ を入力するとインラインリファレンスを作成でき、前回のコールのレスポンスから値をリファレンスできます。

From a callを選択し、解析するレスポンスを含む前回のコールを選択します。レスポンスから必要な値を抽出するための3つのオプションがあります。

• Whole response: レスポンス全体を文字列として抽出します。
• Extract by key: レスポンスのキーを使用して必要な値を抽出します。
• Extract by index: インデックス位置（0インデックス）を使用して配列レスポンスから必要な値を抽出します。

以下の例のように、Extract by keyを選択し、Add nested keyオプションを使用してresultsに続いてunique_idのキーを設定します。

Addを選択すると、ヘッダー値フィールドにリファレンスが表示されます。

キャプチャされる出力パラメーターは、使用しているTask typeによって異なります。

REST Webhookから出力パラメーターをキャプチャし、これらのパラメーターをActionで使用する方法についてさらに詳しく学ぶ。

利便性のため、Webhookタスクの結果は特定のケースで適切な出力パラメータータイプに自動変換されます。

• String出力パラメーターが設定されており、Webhookタスクの結果が文字列でない場合、結果はJSON文字列に変換されます。
• Record出力パラメーターが設定されており、Webhookタスクの結果が文字列の場合、Webhookサービスは文字列をJSONに解析しようとします。
• Double出力パラメーターが設定されている場合、Webhookタスクの結果が整数または長整数であれば自動的に変換されます。

出力パラメーターは、"Test Connection"サイドパネルを介して行われたリクエストのレスポンスを使用して設定できます。テストリクエストが成功すると、レスポンスから解析された提案された出力が新しい出力パラメーターを追加する際に自動的に表示されます。

タスクボディ

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

各タスクが期待する構造は、該当するwebhook typeのエントリの下にリストされる特定のタスクタイプによって異なります。タスクボディは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の場合、タスクボディの構造は外部システムに対して行われるRESTリクエストを表すcallsの配列でなければなりません。

以下は、単一のHTTPコールを表すREST Webhookの基本的なタスクボディテンプレートの例です。

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
    "calls": [
        {
            "type": "magritte-rest-call", // RESTコールのタイプを指定します。ここでは "magritte-rest-call" を使用します。
            "method": "POST", // HTTPメソッドを指定します。ここでは "POST" を使用します。
            "requestMimeType": "application/json", // リクエストのMIMEタイプを指定します。ここでは "application/json" を使用します。
            "path": "your/request/path", // リクエストのパスを指定します。
            "body": { "text": {{json message}} } // リクエストのボディを指定します。ここではjsonメッセージをテキストとして送信します。
        }
    ]
}

このタスクボディテンプレートは、リクエストボディ { text: <message> } で your/request/path エンドポイントに POST リクエストを行います。ここで、 <message> は Webhook の String 入力パラメーターです。

出力パラメーターの抽出

REST Webhook から出力パラメーターを抽出する主な方法は2つあります：1) JSON レスポンスからトップレベルフィールドを名前でキャプチャする、2) よりカスタマイズされた抽出ロジックのための JSON エクストラクターを定義し、出力したいフィールドを明示的にリストアップする。

また、完全なレスポンス JSON を文字列出力として抽出することも選択できます。これにより、後続の編集や通知レンダリングを関数を使用して行う際に、レスポンスをトラバースするための追加の柔軟性が提供されます。

トップレベルフィールドをキャプチャするために、次のレスポンスを返す REST コールを設定したと仮定します：

Copied!
1
2
3
4
{
    // "id"は一意の識別子を示しています
    "id": "c52fd6e4-6eb5-4da1-8908-4845e51c801b"
}

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

レスポンスからネストされたフィールドをキャプチャする必要がある場合は、extractors を指定して値を抽出できます。抽出された値は、その後の呼び出しで使用して呼び出しを連鎖させることもできます。レスポンス全体をキャプチャする必要がある場合は、ルートパスをターゲットとして extractors を指定することで、レスポンス全体を抽出できます: "result": "/".

以下は、いくつかのデータを取得するために GET エンドポイントに 1 回、前の呼び出しのデータを使用して POST エンドポイントに 1 回の 2 回のリクエストを行うタスクボディテンプレートの例です。

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",  // REST APIを呼び出すためのタイプ指定
            "method": "GET",  // HTTPメソッドの指定。ここではGETメソッドを使用
            "path": "path/to/fetchData",  // データを取得するためのパス
            "extractor": [
              {
                "type": "json",  // データ抽出の形式。ここではJSONを指定
                "assign": {
                  "request_output": "/json/path/to/output"  // 抽出したデータの出力先を指定
                }
              }
            ]
        },
        {
            "type": "magritte-rest-call",  // REST APIを呼び出すためのタイプ指定
            "method": "POST",  // HTTPメソッドの指定。ここではPOSTメソッドを使用
            "path": "your/request/path",  // リクエストを送るためのパス
            "body": { "text": {%request_output%} },  // リクエストのボディ部分。前のGETメソッドで取得したデータを使用
            "extractor": [
              {
                "type": "json",  // データ抽出の形式。ここではJSONを指定
                "assign": {
                  "result": "/json/path/to/result"  // 抽出したデータの出力先を指定
                }
              }
            ]
        }
    ],
    "output": ["result"]  // 最終的な出力結果
}

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

その他のオプション

callsとoutputを指定することに加えて、REST Webhookタスクの追加の構成オプションがあります。

• REST Webhookで複数の呼び出しを行う場合、1回の呼び出しのみが安全でないHTTPメソッドを使用することが許可されます。安全でない呼び出しとは、外部システムの状態を変更する可能性のある呼び出しです。デフォルトでは、GET、OPTIONS、およびHEADリクエストのみが安全と見なされます。異なるタイプの呼び出し（たとえば、POSTやPUT）の安全性を上書きするには、呼び出しのフィールドとして"isHttpMethodSafe": trueを指定します。これは、最初の呼び出しの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",  // "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
10
11
12
13
14
15
{
  // "record-type-name": これはレコードのタイプ名を示します。ここでは "Account" と指定されています。
  "record-type-name": "Account",
  // "record-id": これはレコードのIDを示します。具体的な値は {{json record-id}} で指定します。
  "record-id": {{json record-id}},
  // "data": これはレコードのデータ内容を示します。具体的なデータは以下のように指定します。
  "data": {
    // "Name": アカウントの名前を示します。具体的な値は {{json name}} で指定します。
    "Name": {{json name}},
    // "Industry": アカウントの業界を示します。具体的な値は {{json industry}} で指定します。
    "Industry": {{json industry}},
    // "BillingCountry": 請求先の国を示します。具体的な値は {{json country}} で指定します。
    "BillingCountry": {{json country}}
  }
}

delete-record-salesforce-webhook-task

このタスクタイプは この Salesforce API ↗ に対応しています。

Copied!
1
2
3
4
5
6
7
{
  // "record-type-name"はレコードのタイプ名を表します。ここでは"Account"が設定されています。
  "record-type-name": "Account",
  
  // "record-id"はレコードのIDを表します。実際のIDは後で挿入されます。
  "record-id": {{json record-id}}
}

composite-salesforce-webhook-task

collateSubrequestsオプションに関する情報は、Salesforce documentation ↗で確認できます。

以下の例では、最初のサブリクエストで作成されたレコードのIDを参照するために "@{createAccount.id}" を使用しています。依存リクエストの詳細については、Salesforce documentation ↗で学ぶことができます。

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
{
  "request": {
    // "collateSubrequests"は、サブリクエストをまとめるかどうかを決定するフラグです。
    "collateSubrequests": true,
    "compositeRequest": {
      // "createAccount"は新しいアカウントを作成するリクエストです。
      "createAccount": {
        "type": "createRecord",
        "createRecord": {
          // "recordTypeName"はレコードの種類を指定します。ここでは"Account"を指定しています。
          "recordTypeName": "Account",
          "data": {
            // "Name"は作成するアカウントの名前を指定します。{{json name}}はプレースホルダであり、具体的な名前に置き換えられます。
            "Name": {{json name}}
          }
        }
      },
      // "updateId"は既存のアカウントを更新するリクエストです。
      "updateId": {
        "type": "updateRecord",
        "updateRecord": {
          "recordTypeName": "Account",
          "data": {
            // "Industry"はアカウントの業種を更新します。{{json industry}}はプレースホルダであり、具体的な業種に置き換えられます。
            "Industry": {{json industry}}
          },
          // "recordId"は更新するレコードのIDを指定します。"@{createAccount.id}"は作成したアカウントのIDを指定します。
          "recordId": "@{createAccount.id}"
        }
      }
    }
  }
}

SAP

SAP Plugin を使用すると、企業の SAP 環境に接続し、Business APIs ↗ (BAPI) を呼び出して SAP Business Objects を変更できます。SAP ソースを設定した後、特定の BAPI を呼び出す SAP Webhook を作成できます。

現在、SAP Plugin で利用可能なタスクタイプは sap-run-function-webhook-task-v0 のみです。以下に、このタスクタイプのタスクボディの例を示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "function-name": "BAPI_SALESORDER_CHANGE",  // BAPI_SALESORDER_CHANGE 関数の呼び出し
    "inputs": {
        "SALESDOCUMENT": {{json sales-doc-id}},  // 販売文書ID
        "ORDER_HEADER_IN": {
            "PURCH_DATE":  {{json purchase-date}}  // 購入日
        },
        "ORDER_HEADER_INX": {
            "UPDATEFLAG": "U",  // 更新フラグ (U: 更新)
            "PURCH_DATE": "X"  // 購入日を更新対象として指定
        }
    },
    "output": "RETURN",  // 関数の戻り値
    "remote": {
      "context": SAP_CONTEXT_NAME (Optional)  // リモートコンテキスト (オプション)
    }
}

上記のタスクは、与えられた販売文書の購入日を変更するために BAPI_SALESORDER_CHANGE という BAPI を呼び出します。また、Webhook に対してオプションで SAP コンテキストを指定することもできます。

制限

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

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

同時実行制限 は、一度に実行される Webhook 実行の最大数を指定します。これにより、外部システムに対して過剰な同時リクエストを避けることができます。

レート制限 は、指定した時間枠内で Webhook が実行される回数を制限します。Webhook が特定の時間枠ごとに一定の回数しか実行されないことを保証したい場合、このタイプの制限を有効にすることができます。

権限

Webhook の作成、設定、および削除の権限は、関連するソースの権限から拡張されます。

Data Connection の権限についてさらに詳しく知り、Webhook の権限の詳細もご覧ください。

Webhook 履歴

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

デフォルトでは、Webhook に渡された入力と完全な応答は、Webhook を呼び出したユーザーにのみ表示されます。これにより、Webhook コールで渡されるまたは返される機密データが保護されます。webhooks:read-privileged-data 権限を持つと、完全な履歴にアクセスできますが、デフォルトではユーザーにこの権限は付与されていません。この権限を持つカスタムロールが必要です。

その他のオプション

応答の保存

デフォルトでは、Webhook 応答は履歴ビューに 6 か月間保存および表示されます。完全な応答は、Webhook を実行したユーザーと webhooks:read-privileged-data 権限を持つ管理者にのみ表示されます。

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

OAuth 2.0 と Webhooks

認証コードグラント

Palantir Webhooks は、OAuth 2.0 認証コードグラントフローを使用してエンドポイントを呼び出すことをサポートしています。これには、OAuth 2.0 サーバーとの対話を定義するアウトバウンドアプリケーションを使用する必要があります。設定が完了すると、アウトバウンドアプリケーションは REST API Webhook の認証として使用でき、Webhook を実行しようとする個々のユーザーに OAuth サーバーでの認証を促します。

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

Webhooks は、クライアント資格情報を使用して OAuth フローを実行するために使用できます。クライアント資格情報グラントフローは通常、短期間のアクセストークンを取得するために長期間有効なシークレットを使用します。このアクセストークンは、ターゲットシステムに対してアクションを実行するために使用できます。REST API Webhooks は、連続して複数の API コールをチェーンすることをサポートしており、クライアント資格情報のハンドシェイクを実行した後、目的のリクエストを単一の実行として実行できます。

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

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

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

REST API ソースの作成

まず、Data Connection アプリケーションで + New source を作成し、ソースタイプとして REST API を選択します。REST API ソースタイプについてさらに詳しく知ってください。

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

Additional secrets セクションで、新しいシークレットを追加し、トークンエンドポイントにリクエストを送信する際に含まれる ClientSecret を入力します。Webhook コールを構築する際にこの値を参照します。ここに入力された ClientSecret は暗号化され、Foundry の他の編集者や所有者にも公開されません。

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

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

Webhook は 2 つのチェーンされたコールで構成されます。

• 有効なベアラートークンを取得するための最初のコール
• 取得したベアラートークンを使用して、リソースドメイン 上の目的のエンドポイントにリクエストを送信する次のコール

最初のコールを構成する方法の例を以下に示します。

2 番目のコールでは、利用可能な構成オプションを使用して目的のリクエストを構築します。認証ヘッダーにベアラートークンを挿入するには、コール構成の Headers セクションに移動し、以下の例に示すようにヘッダーを追加します。@ を使用して前のコールの値を参照できます。多くの OAuth 2.0 サーバーは、access_token または類似の JSON パラメーターを返します。コールから 値を追加するオプションを選択し、キーによる抽出 を選択して、最初のコールの応答から抽出したいキーの値を入力します。

最初のコールからベアラートークンを選択する方法の例を以下のスクリーンショットに示します。

構成が完了すると、2 つのチェーンされたコールを持つ完了した Webhook は次の例のようになります。

最後に、Webhook の最初のコールの完全な応答の保存を無効にすることを強くお勧めします。応答が保存される場合、ベアラートークンが含まれているため、完全な Webhook 履歴を表示する権限を持つ他のユーザーに表示される可能性があります。通常、Webhook 構成の Storage and retention ページでトークンエンドポイントへのリクエストの履歴保存を無効にするための自動プロンプトが表示されます。以下に示すように警告ポップアップが表示されます。