Data connectorsは、FinがAPIエンドポイントを介して外部システムと連携することを可能にします。FinはData connectorsを使って以下のことができます:

外部システムからライブデータを読み取り、手順内で使用します（例：顧客のプラン確認、注文状況の照会、アカウント詳細の取得など）。
外部システムに書き戻しを行い、会話中にアクションを実行します（例：サブスクリプションのキャンセル、レコードの更新、POST、PUT、PATCH、DELETEリクエストによる返金処理など）。

Procedure内でData connectorが実行されると、その応答は会話の期間中、Finに一時的なコンテキストとして利用可能になりますが、自動的に連絡先や会話属性に永続化されるわけではありません。データをIntercomに永続的に保存する必要がある場合（例：カスタム連絡先属性やCustom Objectへの保存）、コネクタ設定でオブジェクトマッピングを構成する必要があります。

始めましょう

InstructionステップにData connectorを追加する

Instructionステップ内で@を入力してツールメニューを開きます。
Call data connectorを選択します。
実行したい特定のコネクタを選択します（例：顧客の購入履歴を取得するGet orders）。

ヒント: Data connectorsの設定方法を学び、内部システムやサードパーティAPIからライブ情報を直接Fin Proceduresに取り込みましょう。

自動生成された属性を使って応答にアクセスする

コネクタを追加すると、以降のステップで応答にすぐアクセスできます。これはFinにコンテキストとして一般的に利用可能ですが、応答フィールドをData connectorsに解析して、応答本文の項目を明示的に参照できるようにしています。

注意: ProcedureでData connectorsを使う際、応答マッピングは必須ではありません。FinはData connectorで設定したテスト応答を使ってAPI応答の構造（利用可能なフィールド名と型）を理解します。その後、手順の指示で自然言語を使い、どの応答データを使うかFinに伝えます。実行時にはFinがライブAPIコールを行い、実際の値を読み取ります。

@を入力し、Read an attributeを選択します。
Data connectorの応答フィールドがドロップダウンの上部に自動的にリスト表示されます（例：Get delivery order > status、Get delivery order > order_id）。
必要な特定の属性を選択して、指示や条件に挿入します。

コンテキストはProcedure全体で共有されます

FinにData connectorの使用を指示すると（@ use data connector）、返されたデータはProcedure全体で利用可能になります。

より信頼性を高めるために、(@ read attributes)を使ってこのデータにアクセスできます。FinはProcedureの全期間（すべてのステップとサブプロシージャを含む）でコネクタデータを保持します。明示的にデータを更新する必要がない限り、各コネクタはProcedureごとに一度だけ呼び出せば十分です。

例えば、ステップ1で(@ use Get_Subscription_info)を呼び出すと、Finはその後のすべてのステップとサブプロシージャで顧客のサブスクリプションコンテキストを保持します。

ベストプラクティス

モックData connectorsを活用してProcedureのテストと構築を始めましょう

完全なライブAPIがなくてもProcedureの構築を開始できます。例示応答を使ってデータをシミュレート可能です。

例示応答: Data Connector設定の「Test response」タブで例示応答を選択し、モックJSONペイロードを貼り付けます。これにより、すぐにProcedureのフローを構築・テストできます。
動的モック: より複雑なシナリオでは、Beeceptorなどのツールを使って動的API応答をシミュレートできます。

FinがProcedureで必要とする関連データの最小限のサブセットになるようAPI応答を最適化しましょう

不要なデータが多すぎるとパフォーマンスに影響します。一般的に、より小さく明確な方が良いです。

データ変換が必要な場合は、フィールド数を限定するかdata connector code blocksを使って変換することを強く推奨します。これにより、FinがProcedureで見る前にAPI応答が変換されます。

ステップごとにData connectorは1つまでに最適化しましょう

ステップは単一の作業単位を意図しています。Finは1つのステップで1つのData connectorを呼び出すと最も信頼性が高くなります。

コンテキストごとにData connectorsは1回だけ呼び出す

Procedureにおける「コンテキスト」とはProcedure全体の実行を指します。Finはすべてのステップとサブプロシージャでコネクタデータを自動的に再利用します。同じAPIを2回呼び出す必要はありません。

❌ ステップ間で同じコネクタを2回呼び出す必要はありません:

Step 1: 

… (@use Get_Subscription_info) … and include @read plan status in your response so the users knows 

Step 2 

… (@use Get_Subscription_info) …  and include @read refund eligibility in your response so the users knows

✅ コネクタは1回呼び出すだけの方が簡単で、クリーンで高速です:

Step 1: 

… (@use Get_Subscription_info) … include @read plan status in your response so the users knows 

Step 2 

… include @read refund eligibility in your response so the users knows

複数のシステムからデータが必要な場合は、1つのステップで複数のコネクタを呼び出すのではなく、複数のステップにロジックを分割しましょう。

Finに既にData connectorの必須入力として設定されているデータを収集させる必要はありません

入力はData connector設定時に事前構成されているため、Finは明示的にデータ収集を指示しなくても必要な入力を推測して収集します。

例えば、Data connector Get Order Detailsにすでにemail入力フィールドが設定されている場合:

❌ 不必要に複雑な指示:

First ask the customer for their email, then call @get_order_details with that email

✅ 明確な指示:

Call @get_order_details

Finは、入力がIntercomから直接提供されていない限り、コネクタ設定に基づいて必要な入力を自動的に推測して収集します。

注意: 入力収集にパフォーマンスや信頼性の問題がある場合は、Finに明示的にいつデータを収集するか指示できます。

プロのヒント: Procedureで正確で変更されていない安全なデータ（例：メール、ユーザーID、アカウント情報）が必要な場合は、それらの値をIntercomから直接コネクタに注入しましょう。Finが収集や推論を行わず、データがそのまま保持されます。

一時属性をData Connectorsの決定的な入力として使用する

Data Connectorパラメータの入力元として一時属性を選択できるようになりました。一時属性が入力にマッピングされると、Finは属性取得ロジックをスキップし、一時属性の値を直接使用します。推論も顧客への質問もフォールバックもありません。

これは、Procedureの前のステップで値を収集または設定した場合（例：Update: Temporary Attributeアクション経由）、その正確な値をコネクタに渡したいときに便利です。

設定するには、ProcedureのData Connectorステップを開き、マッピングしたい入力パラメータを見つけ、Sourceドロップダウンをクリックしてリストから一時属性を選択します。

重要: 一時属性がData Connectorステップ実行前に設定されていない場合、Finは会話イベントでエラーを表示します。コネクタ呼び出し前にProcedureの前のステップで属性を設定してください。

コネクタの状態監視

Data connectorsを使うProcedureは、ProcedureリストページにConnector issuesインジケーターが表示され、各Procedureを開かずに問題を一目で確認できます。この表示は過去14日間の最悪のパフォーマンスのコネクタに基づきます（コネクタごとに最大1,000回の実行を対象）。

Data connectorsを使わないProcedureにはインジケーターは表示されません。実行回数がゼロのコネクタは正常とみなされます。

注意: Data connectorの成功率は選択した期間フィルターに基づきます。問題を修正した後、新しいデータを待つか期間フィルターを調整して成功を確認してください。

状態ステータス

ステータス	基準	影響
🟡 劣化	いずれかのコネクタの成功率が80～95％、または成功率が95％以上でも平均応答サイズが50KB以上（約15Kトークン）。	問題が発生しているか、幻覚リスクを高める大きな応答を返しています。
🔴 不健康	いずれかのコネクタの成功率が80％未満、または平均応答サイズが100KB以上（約30Kトークン）。	重大な問題があるか、即時対応が必要な危険な大きな応答です。

詳細分析

Connector issuesインジケーターをクリックすると、影響を受けた各コネクタのカードが表示され、ステータス（劣化または不健康）、成功率、実行回数、応答サイズが確認できます。コネクタ名は設定ページへのリンクになっており、迅速なデバッグが可能です。

配列の扱い

Data connectorがリストを返す場合、Finはルート配列のみを属性として公開します。配列内の子要素は属性ピッカーで別の属性としては表示されません。

例えば、コネクタがitems配列を返す場合、以下が表示されます:

Get orders > items

しかし、以下は表示されません:

Get orders > items > title
Get orders > items > price

Finはリストの内容を扱うことができます。例えば、「顧客が注文内容を尋ねたら、Get order > itemsを使って商品と価格を一覧表示する」という指示を与えた場合、

Finはitemsリストの全内容を読み取り、「ご注文にはワイヤレスマウス（$24.99）とノートパソコンスタンド（$39.99）が含まれています」と応答します。

例: 以下の応答ペイロードでは、ルート配列要素itemsのみが一時属性として公開され、その子要素は公開されません。

{
  "order_id": "ORD-1001",
  "status": "processing",
  "created_at": "2025-01-12T14:23:00Z",
  "items": [
    {
      "product_id": "PROD-200",
      "name": "Wireless Mouse",
      "quantity": 1,
      "unit_price": 24.99
    },
    {
      "product_id": "PROD-122",
      "name": "Laptop Stand",
      "quantity": 1,
      "unit_price": 39.99
    }
  ]
}

注意: @Read Get orders > itemsを使い、顧客に注文の上位3つのアイテムを伝えます。

コード条件での配列の使用

配列属性はinputs["data_connector"]オブジェクト内にあり、Data connector名ごとにグループ化されています。配列は0始まりで、最初のアイテムはインデックス0です。特定のインデックスにアクセスする前に必ず配列の長さを確認してください。

コード条件では、Python式を使って配列データにアクセスできます。インデックスで明示的にアイテムを参照したり、リストを反復処理したりします。

この条件は、注文に少なくとも4つのアイテムがあり、4番目のアイテムの数量が3より大きいことをチェックします。

条件評価中の実行時エラーを避けるため、インデックスにアクセスする前に必ず配列の長さを検証してください。

注意: 利用可能なアクションはData connectorの設定によります。

Data connectorsは以下をサポートします:

作成: POSTリクエストを使って外部システムに新しいレコードを作成します。
読み取り: GETリクエストを使って既存データを取得します。
更新: PUTまたはPATCHリクエストを使って既存レコードを修正します。
削除: DELETEリクエストを使ってレコードを削除します。

Fin Proceduresでデータコネクタを使用する方法