データコネクタはFinがAPIエンドポイントを介して外部システムと連携することを可能にします。Finはデータコネクタを使って以下のことができます：

データコネクタから情報を読み取る（例：ユーザーのプラン情報）。
アクションを実行する（例：POSTを使って外部システムでサブスクリプションをキャンセルする）。

始める

Instructionステップにデータコネクタを追加する

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

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

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

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

注意：Proceduresでデータコネクタを使う場合、レスポンスマッピングは不要です。Finはデータコネクタで設定したテストレスポンスを使い、APIレスポンスの構造と利用可能なフィールド名・型を理解します。その後、手順の指示で自然言語を使い、どのレスポンスデータを使うかFinに伝えます。実行時にはFinがライブAPIコールを行い、実際の値を読み取ります。

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

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

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

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

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

ベストプラクティス

モックデータコネクタを活用して手順のテストと構築を始めましょう

ライブAPIが完全に構築されていなくても、例示レスポンスを使ってデータをシミュレートできます。

例示レスポンス：データコネクタ設定の「Test response」タブで例示レスポンスを選び、モックJSONペイロードを貼り付けます。これにより手順のフローをすぐに構築・テストできます。
動的モック：より複雑なシナリオでは、Beeceptorなどのツールを使って動的APIレスポンスをシミュレートできます。

Finが手順で必要とする関連データの最小限のサブセットになるようAPIレスポンスを最適化しましょう

不要なデータが多すぎるとパフォーマンスに影響します。一般的に小さく簡潔なほうが良いです。

データ変換が必要な場合は、フィールド数を限定するかデータコネクタコードブロックを使って変換することを強く推奨します。これによりFinが手順で見る前にAPIレスポンスが変換されます。

ステップごとにデータコネクタは1つまでに最適化する

ステップは単一の作業単位を意図しています。Finは1ステップで1つのデータコネクタを呼び出すと最も信頼性が高いです。

コンテキストごとにデータコネクタを呼び出す

Proceduresでは「コンテキスト」とはProcedure全体の実行を指します。Finはすべてのステップとサブプロシージャでコネクタデータを自動的に再利用します。同じAPIを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

✅ コネクタは一度だけ呼び出すほうが簡単で、クリーンで高速です：

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に既にデータコネクタの必須入力として設定されているデータを収集させる必要はありません。

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

例えば、データコネクタ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が収集や推論を介さずにデータがそのまま渡されます。

コネクタの状態監視

データコネクタを使うProceduresは、手順リストページにConnector issuesインジケーターが表示され、各手順を開かずに問題を一目で確認できます。この表示は過去14日間の最悪のパフォーマンスのコネクタを反映し（1,000回の実行上限あり）、

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

注意：手順リストのConnector issuesインジケーターは常に過去14日間を反映します。データコネクタのヘルスダッシュボードの成功率は選択した期間フィルターに従います。問題修正後は新しいデータを待つか期間フィルターを調整して成功を確認してください。

ヘルスステータス

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

詳細分析

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

配列の扱い

データコネクタがリストを返す場合、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"]オブジェクト内に、データコネクタ名ごとにグループ化されて利用可能です。配列は0始まりで、最初のアイテムはインデックス0です。特定のインデックスにアクセスする前に必ず配列の長さを確認してください。

コード条件では、Python式を使って配列データにアクセスし、インデックス指定やリストの反復処理を明示的に行います。

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

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

注意：利用可能なアクションはデータコネクタの設定によります。

データコネクタは以下をサポートします：

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

Fin Proceduresでのデータコネクタの使い方

始める