設定リファレンス

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

入力と出力の設定

各 Webhook は、外部システムに対する要求に 入力パラメーター をマッピングするために、柔軟に設定することができます。その後、そのシステムからの応答を 出力パラメーター としてキャプチャし、それを Palantir Foundry の他の場所で使用することができます。

入力パラメーター

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

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

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

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

• リスト パラメーターは特定の型の入力の順序付きコレクションを表します。
• レコード パラメーターはキー/値のペアを渡すことを可能にし、特定のキーを特定の型の値とともに必須にすることができます。
• オプショナル パラメーターは存在するかもしれない、または存在しないかもしれない入力を表します。

最後に、アクションフォームでアップロードされたファイルを渡すために使用できる アタッチメント タイプもあります。ただし、webhook がエージェントで実行される場合、アタッチメントはサポートされていません。

出力パラメーター

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

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

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

{
  // 結果
  "results": {
    // 固有ID
    "unique_id": "ID4567"
  }
}

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

呼び出しからを選択し、解析するレスポンスを持つ前の呼び出しを選択します。レスポンスから必要な値を抽出するための3つのオプションが用意されています：

• 全レスポンス： 全レスポンスを文字列として抽出します。
• キーによる抽出： レスポンスのキーを使用して必要な値を抽出します。
• インデックスによる抽出： 配列レスポンスからインデックス位置（ゼロインデックス）を使用して必要な値を抽出します。

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

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

キャプチャされる出力パラメーターは、使用しているタスクタイプに依存します。

REST Webhookから出力パラメーターをキャプチャし、これらのパラメーターをアクションで使用する方法について詳しく学びましょう。

便宜上、Webhookタスクの結果は、特定のケースでは適切な出力パラメータータイプに自動的に変換されます：

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

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

タスクボディ

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

各タスクが期待する構造は、そのwebhookタイプのエントリーの下にリストされる特定のタスクタイプによります。タスクボディはHandlebars構文を使用して定義する必要があります。タスクボディ内では、上記で文書化したように、Webhookに定義した入力パラメーターを任意のものに参照できます。

Webhookタイプ

各Webhookタイプは、異なる設定オプションをサポートします。このセクションでは、各種Webhookタイプで利用可能なオプションを文書化し、基本的な例を提供して、始めるための手助けをします。

REST API

Webhooksの最も一般的な使用方法は、REST APIにHTTPリクエストを行うことです。REST APIソースを設定した後、リクエストビルダーインターフェースを使用して行いたいリクエストを構築できます。

REST APIソースに利用可能なオプションは以下のとおりです：

複数のリクエスト

単一のWebhookには複数のリクエストが含まれることがあります。リクエストはチェーン化することができ、前の呼び出しのレスポンス値が後続の呼び出しで参照されます。

REST API（レガシー）

magritte-rest-v2ソースを設定した後、generic-rest-webhook-taskを使用してREST Webhooksを作成できます。

REST Webhookの場合、タスクボディの構造は、外部システムに対して行われるRESTリクエストを表すcallsの配列でなければなりません。

以下は、REST Webhookの基本的なタスクボディテンプレートの例で、単一のHTTP呼び出しを表します：

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
    "calls": [
        {
            "type": "magritte-rest-call", // マグリットのREST呼び出しのタイプ
            "method": "POST", // POSTメソッド
            "requestMimeType": "application/json", // リクエストのMIMEタイプ: application/json
            "path": "your/request/path", // リクエストパス
            "body": { "text": {{json message}} } // リクエストボディ: JSONメッセージ
        }
    ]
}

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

出力パラメーターの抽出

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": "/"。

以下は、2つのリクエストを行うタスクボディテンプレートの例です。1つはGETエンドポイントからデータを取得するためのもの、もう1つは前の呼び出しからのデータを使用して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",  // "magritte-rest-call"というタイプの呼び出しです
            "method": "GET", // HTTPメソッドはGETです
            "path": "path/to/fetchData", // データを取得するためのパスです
            "extractor": [ // この配列はデータを抽出するための設定です
              {
                "type": "json", // データタイプはJSONです
                "assign": { 
                  "request_output": "/json/path/to/output" // 抽出したデータをこのパスに割り当てます
                }
              }
            ]
        },
        {
            "type": "magritte-rest-call", // "magritte-rest-call"というタイプの呼び出しです
            "method": "POST", // HTTPメソッドはPOSTです
            "path": "your/request/path", // リクエストを送るパスです
            "body": { "text": {%request_output%} }, // リクエストのボディには前の呼び出しの結果が含まれます
            "extractor": [ // この配列はデータを抽出するための設定です
              {
                "type": "json", // データタイプはJSONです
                "assign": {
                  "result": "/json/path/to/result" // 抽出したデータをこのパスに割り当てます
                }
              }
            ]
        }
    ],
    "output": ["result"] // 最終的な結果はこの配列に格納されます
}

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

その他のオプション

calls や output を指定する他に、REST Webhookタスクにはいくつかの追加設定オプションがあります：

• REST Webhookで複数の呼び出しを行っている場合、安全でないHTTPメソッドを使用した呼び出しは1つだけ許可されます。安全でない呼び出しとは、外部システムの状態を変更する可能性があるものを指します。デフォルトでは、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 webhooksには以下のタスクタイプが利用可能です：

• create-record-salesforce-webhook-task: 与えられたタイプのSalesforceレコードを作成します。
• update-record-salesforce-webhook-task: 与えられたタイプのSalesforceレコードを更新します。
• delete-record-salesforce-webhook-task: Salesforceレコードを削除します。
• composite-salesforce-webhook-task: Salesforceのcomposite requestを使用して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",  // レコードタイプ名："Account"（アカウント）
  "record-id": {{json record-id}},  // レコードID
  "data": {
    "Name": {{json name}},  // 名前
    "Industry": {{json industry}},  // 業界
    "BillingCountry": {{json country}}  // 請求国
  }
}

delete-record-salesforce-webhook-task

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

Copied!
1
2
3
4
5
6
{
  // "record-type-name" は "Account" というレコードタイプの名前を示します
  "record-type-name": "Account",
  // "record-id" は特定のレコードのIDを示します
  "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
27
28
29
30
31
32
33
34
35
36
{
  "request": {
    // "collateSubrequests"は、すべてのサブリクエストが終了するまでメインリクエストの終了を待つかどうかを示します。
    // trueに設定すると、すべてのサブリクエストが終了するのを待ちます。
    "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"という種類のレコードを更新します。
          "recordTypeName": "Account",
          "data": {
            // "Industry"は更新するレコードの業界情報を示します。ここでは{{json industry}}という値が設定されます。
            "Industry": {{json industry}}
          },
          // "recordId"は更新するレコードのIDを示します。ここでは"@{createAccount.id}"という値が設定されます。
          // これは上記の"createAccount"で作成したレコードのIDを指しています。
          "recordId": "@{createAccount.id}"
        }
      }
    }
  }
}

SAP

SAP プラグインを使用すると、ユーザーの企業 SAP 環境に接続し、ビジネス API（BAPI）を呼び出して SAP ビジネスオブジェクトを変更できます。SAP ソースを設定した後、特定の BAPI に呼び出す SAP Webhook を作成できます。

現在、SAP プラグインで利用可能なタスクタイプは sap-run-function-webhook-task-v0 のみです。以下は、このタスクタイプのタスクボディの例です。

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
{
    "function-name": "BAPI_SALESORDER_CHANGE",
    // 関数名: 売上伝票の変更
    "inputs": {
        "SALESDOCUMENT": {{json sales-doc-id}},
        // 入力: 売上伝票ID
        "ORDER_HEADER_IN": {
            "PURCH_DATE":  {{json purchase-date}}
            // 注文ヘッダ_入力: 購入日
        },
        "ORDER_HEADER_INX": {
            "UPDATEFLAG": "U",
            // 注文ヘッダ_インデックス: 更新フラグ
            "PURCH_DATE": "X"
            // 購入日: 更新対象
        }
    },
    "output": "RETURN",
    // 出力: 戻り値
    "remote": {
      "context": SAP_CONTEXT_NAME (Optional)
      // リモート: SAPコンテキスト名 (オプション)
    }
}

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

制限

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

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

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

レート制限では、ユーザーが指定した時間枠内にWebhookが実行できる回数を制限します。Webhookが毎秒、毎分、毎時間、または毎日特定の回数だけ実行することを保証したい場合、このタイプの制限を有効にできます。

権限

Webhookの作成、設定、削除の権限は、関連するsourceの権限から拡張されます。

Data Connectionの権限について詳しく知るとともに、Webhookの権限に関する詳細を参照してください。

その他のオプション

レスポンスの保存

デフォルトでは、Webhookのレスポンスは6ヶ月間履歴ビューに保存され、表示されます。完全なレスポンスは、Webhookを実行したユーザーと、webhooks:read-privileged-data の権限を持つ任意の管理者にだけ表示されます。

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

OAuth 2.0 と Webhooks

認可コードグラント

PalantirのWebhooksは、OAuth 2.0認可コードグラントフローを使用したエンドポイントの呼び出しをサポートしています。これには、OAuth 2.0サーバーとのインタラクションを定義するためのoutbound applicationの使用が必要です。設定が完了すると、outbound applicationはREST API Webhookの認証として使用でき、個々のユーザーはWebhookの実行を試みるときにOAuthサーバーで認証するように求められます。

クライアントクレデンシャルズグラント

Webhooksは、クライアントクレデンシャルズを使用したOAuthフローの実行に使用することができます。クライアントクレデンシャルズグラントフローは通常、長寿命のシークレットを使用して短寿命のアクセストークンを取得し、そのアクセストークンを使用してターゲットシステムに対するアクションを実行します。REST API Webhookは連鎖的な複数のAPI呼び出しをサポートし、クライアントクレデンシャルズのハンドシェイクを行った後に必要なリクエストを単一の実行として行うことができます。

以下のウォークスルーでは、概念的な例システムに対するクライアントクレデンシャルズグラントフローの設定方法を説明します。

進行するためには、以下の情報が必要です：

• OAuth 2.0サーバーのドメインとトークンエンドポイントへのパス。トークンエンドポイントは、リソースドメインへのリクエストを行うための有効なトークンを取得するために使用されます。
  • 多くの場合、OAuth 2.0サーバーのドメインとリソースドメインは同一です。例えば、第三者アプリケーションを使用してFoundry APIで認証を行う場合がこれに該当します。
• ベアラートークンを含むAuthorizationヘッダーを使用して呼び出す予定のリソースドメインと目的のエンドポイントへのパス。
• OAuth 2.0サーバーのクライアントID。
• OAuth 2.0サーバーのクライアントシークレット。

REST APIソースの作成

まず、Data Connectionアプリケーションで**+ 新規ソースを作成し、ソースタイプとしてREST API**を選択します。REST APIソースタイプについて詳しく知ることができます。

ソースの設定時に、OAuth 2.0サーバードメインとリソースドメインを追加し、以下に示すように入力します。認証オプションは選択しないでください。OAuth 2.0のハンドシェイクはWebhook呼び出しの連続の中で直接手動で行います。

追加のシークレットのセクションで、新しいシークレットを追加し、トークンエンドポイントへのリクエストを行う際に含まれるClientSecretを入力します。この値は、Webhook呼び出しを構築する際に参照します。ここに入力すると、ClientSecretは暗号化され、Foundryのソースの他のエディターや所有者にも公開されません。

クライアントクレデンシャルズハンドシェイクを実行するWebhookの作成

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

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

• 有効なベアラートークンを取得するための初期のトークンエンドポイントへの呼び出し
• パースされたベアラートークンを含む、リソースドメイン上の所望のエンドポイントへの後続の呼び出し。

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

二番目の呼び出しでは、利用可能な設定オプションを使用して所望のリクエストを構築します。ベアラートークンを認証ヘッダーに注入するには、呼び出し設定のヘッダーセクションに移動し、以下の例に示すようにヘッダーを追加します。@を使用して前の呼び出しからの値を参照することができます。ほとんどのOAuth 2.0サーバーは、access_tokenまたは類似のJSONパラメーターを返します。値を追加するオプションを選択し、呼び出しからの値を選択し、最初の呼び出しのレスポンスから抽出したいキーの値を入力します。

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

設定が完了すると、2つのチェーンドコールを持つ完成したWebhookは、この例に類似したものになるはずです：

最後に、Webhookの最初の呼び出しからの完全なレスポンスの保存を無効にすることを強くお勧めします。レスポンスが保存されている場合、それらに含まれるベアラートークンが、完全なWebhook履歴を表示する権限を持つ他のユーザーに見える可能性があります。トークンエンドポイントへのリクエストの履歴を保存しないようにするための自動プロンプトが通常、Webhook設定のストレージと保持ページに表示されます。これは以下に示すようになります：