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

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

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

始めましょう

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

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

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

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

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

注意：Procedureでデータコネクタを使う際、応答マッピングは必須ではありません。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応答を最適化しましょう

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

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

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

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

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

入力はデータコネクタ設定時に事前構成されているため、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が収集・推論することなくデータがそのまま渡されます。

一時属性をデータコネクタの決定的な入力として使う

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

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

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

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

コネクタの状態監視

データコネクタを使うProcedureは、Procedure一覧ページにヘルスインジケーターが表示され、各Procedureを開かずにコネクタの問題を一目で確認できます。このスタンプは過去14日間の最もパフォーマンスの悪いコネクタを反映し（1コネクタあたり最大1,000回の実行を対象）、

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

ヘルスステータス

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

詳細分析

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

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

配列の扱い

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