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

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

始める

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

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

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

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

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

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

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

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

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

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

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

ベストプラクティス

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

完全なライブAPIがなくても手順の構築を始められます。例示的なレスポンスを使ってデータをシミュレートできます。

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

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

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

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

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

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

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

手順では「コンテキスト」とは手順全体の実行を指します。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に既にデータコネクタの必須入力として設定されているデータを収集させる必要はありません。

入力はデータコネクタ設定時に事前構成されているため、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に明示的にいつデータを収集するか指示できます。

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

コネクタの状態監視

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

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

注意：データコネクタの成功率は選択した期間フィルターに基づきます。問題を修正した後、新しいデータが反映されるまで待つか、期間フィルターを調整して成功を確認してください。

状態

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

詳細分析

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

配列の扱い

データコネクタがリストを返す場合、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番目です。特定のインデックスにアクセスする前に必ず配列の長さを確認してください。

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

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

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

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

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

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

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

始める