API Connector テストガイド

このドキュメントでは、プロンプトカードの「API Connector」機能をテストするためのサンプルAPIと、その設定方法について説明します。

1. 基本的な設定方法

API Connectorカードを作成し、以下の項目を設定します。

• API URL: 取得先のURL（https://... または /api/...）
• Method: GET または POST
• JSON Selector: レスポンスのJSONから特定の値を抽出するためのドット記法（例: data.text）
• Headers (JSON): {"Authorization": "Bearer ...", "Accept": "application/json"} のような形式で指定
• Body (JSON): POSTリクエスト時に送信するデータ

プロンプトの本文（Content）欄に {{DATA}} を含めると、取得したデータがその場所に埋め込まれます。含めない場合は、コンテンツの先頭にデータが自動的に挿入されます。

---

2. テスト用サンプルAPI案

案A: 公開されているシンプルなJSON API (GET)

外部ネットワークへの接続確認に適しています。

• API URL: https://official-joke-api.appspot.com/random_joke
• Method: GET
• JSON Selector: setup (または punchline)
• 期待される結果: ランダムなジョークの冒頭部分が埋め込まれる

案B: 構造化データの抽出テスト (GET)

ネストされたオブジェクトからの抽出を確認します。

• API URL: https://api.open-meteo.com/v1/forecast?latitude=35.6762&longitude=139.6503&current=temperature_2m
• Method: GET
• JSON Selector: data.current.temperature_2m
• 期待される結果: 20.5 のような数値（現在の東京の気温）

案C: クエリパラメータやカスタムHeaderのテスト (GET)

外部ネットワークへの接続確認に適しています。

• API URL: https://httpbin.org/get?name=PlotToProse
• Method: GET
• Headers (JSON): {"X-Custom-Header": "TestValue"}
• JSON Selector: data.headers.X-Custom-Header
• 期待される結果: "TestValue"

案D: POSTリクエストのテスト

データの送信とレスポンスの受け取りを確認します。

• API URL: https://httpbin.org/post
• Method: POST
• Body (JSON): {"test_input": "Hello World"}
• JSON Selector: data.json.test_input
• 期待される結果: "Hello World"

---

3. 実装上の改善点（反映済み）

ガイド作成にあたり、以下の機能を「API Connector」に追加実装しました。

1. Method選択 (GET/POST): 単純な取得だけでなく、データの送信を伴うリクエストも可能にしました。
2. カスタムHeader (JSON): Authorization などの認証用ヘッダーや、Accept 等のコンテントタイプ指定を手動で行えるようにしました。
3. Request Body (JSON): POSTメソッド使用時に、任意のJSONデータを送信できるようにしました。
4. 型定義の拡張: DynamicConfig インターフェースに apiHeaders と apiBody を追加し、永続化に対応させました。
5. エラーハンドリングの強化: JSONのパース失敗時にログ出力を行い、可能な限り元の文字列を維持してフォールバックするように調整しました。

4. トラブルシューティング

• ECONNRESET エラー: ネットワーク環境やプロキシの制限により接続が切断されることがあります。再試行ロジックが組み込まれていますが、頻発する場合はAPIサーバー側の制限も確認してください。
• Selectorが効かない: コンソールログ（F12）を開き、📦 [PromptResolver] API Response Structure というグループを探してください。実際のJSON構造とSelectorが一致しているか確認できます。
• 内部API (/api/...): 内部APIを叩く場合は、/api/proxy を経由せずブラウザから直接リクエストが送信されます。