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

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

始めましょう

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

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

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

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

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

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

@を入力し、Read an attributeを選択します。
データコネクタのレスポンスフィールドがドロップダウンの上部に自動的に表示されます（例：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つのデータコネクタを呼び出すと最も信頼性が高いです。

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

手順では「コンテキスト」とは手順全体の実行を指します。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コネクタあたり最大1,000回の実行を対象）、

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

ヘルスステータス

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

詳細表示

ヘルススタンプをクリックすると、各コネクタのステータス、成功率、平均レスポンスサイズ、P90レイテンシ、主要エラーの内訳が表示されるドロワーが開きます。コネクタ名は設定ページへのリンクになっており、迅速なデバッグが可能です。

ヒント：レスポンスサイズが原因で劣化または異常が表示されている場合は、上記のFinが必要とする関連データの最小限のサブセットになるようAPIレスポンスを最適化するベストプラクティスを参照し、フィールドの絞り込みやコードブロックの使用でFinが見る前にレスポンスをトリムするのが最速の解決策です。

配列の取り扱い

データコネクタがリストを返す場合、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
    }
  ]
}