API ポーリング

アプリで開く

エージェント設定 → API Poll — AnySoul の設定パネルから直接 poll endpoint を設定できます。

API ポーリングを使うと、エージェントが外部 REST API から定期的にデータを取得できます。外部システムからプッシュを受け取る Webhook とは異なり、ポーリングはスケジュールに基づいてデータをプルします——ブラウザが直接 HTTP リクエストを実行します。

設定、認証情報、スケジューリングはすべてブラウザ内で完結します。サーバーはポーリングの存在を一切認識しません。

仕組み

1. ブラウザの setInterval タイマーが発火
2. ブラウザが外部 API を直接呼び出す（認証情報は AnySoul サーバーを経由しない）
3. レスポンスをイベントフィールドにマッピング（Webhook と同じテンプレートエンジン）
4. オプションの SHA-256 diff チェックで重複データをスキップ
5. マッピング結果は自動作成された Bridge Webhook を通じてサーバーに送信——既存の Webhook ingest endpoint を再利用し、サーバー側の変更はゼロ

Poll Endpoint の作成

1. エージェント設定 → API Poll を開く
2. 追加 をクリック
3. 以下を入力:
   • 名前 — この poll のラベル（例: tokyo-weather、btc-price）
   • URL — 呼び出す API endpoint（http:// と localhost も OK）
   • メソッド — GET または POST
   • 認証 — 認証モードを参照
   • 間隔 — ポーリング間隔（1 秒〜24 時間）
   • JSON Path — レスポンスからネストされたオブジェクトを抽出（例: data.items）
   • 重複排除モード — Full（毎回イベント作成）または Diff（データ変更時のみ）
4. 作成 をクリック

新しい poll はテストモードで作成されます。Test Now でレスポンスを確認し、マッピングを設定してから正式上線してください。

テストモード

poll がテストモードの場合:

1. poll カードの Test Now をクリック
2. ブラウザが外部 API を呼び出し、生のレスポンスを表示
3. マッピング ダイアログでレスポンスからイベントフィールドへのマッピングを設定
4. ライブプレビューを確認
5. 正式上線 をクリックして有効化——ポーリングタイマーが開始し、成功するたびにイベントが作成される

テストモードでは、イベントを作成せずに設定を反復できます。

localhost にアクセス可能

ポーリングはブラウザ内で実行されるため、http://localhost やローカルネットワークアドレスにネイティブにアクセスできます。Home Assistant、NAS API、ローカル開発サーバーなどの内部サービスに最適です。

認証モード

モード	ヘッダー / パラメータ	ユースケース
None	—	公開 API、localhost サービス
Bearer Token	Authorization: Bearer <token>	OAuth トークンまたは固定 Bearer トークンを使う API
API Key (Header)	カスタムヘッダー（例: X-API-Key）	特定ヘッダーに key が必要な API
API Key (Query)	クエリパラメータ（例: ?appid=xxx）	OpenWeatherMap のようにクエリ文字列で key を渡す API

すべての認証情報は IndexedDB に保存され、ブラウザの外に出ることはありません。

注意

認証情報は IndexedDB に平文で保存されます——BYOK API key の localStorage と同じセキュリティモデルです。ブラウザデータを消去すると poll 設定は削除されます。エクスポートでバックアップしてください。

ビジュアルマッピング

マッピングダイアログは Webhook のマッピングエディターと同一です:

• 左パネル — テストレスポンスの JSON ツリー。フィールドをクリックするとマッピング式が自動挿入されます。
• 右パネル — 5 つのターゲットフィールド:

フィールド	キー	必須	例
Platform	platform	いいえ	api-poll
Element	element	いいえ	weather
Event Type	event_type	いいえ	update
Title	title	はい	{{ payload.weather.0.description }} — {{ payload.main.temp }}°C
Payload	payload	いいえ	{{ payload.main }}

テンプレート構文は共通です——テンプレート構文を参照。

エージェントが見る内容

ポーリングイベントは Webhook イベントとまったく同じ形式でエージェントのイベントストリームに表示されます:

- [02-22 09:00] [evt_xyz789] api-poll/weather (update): scattered clouds — 12.5°C

エージェントはプッシュとプルを区別しません——単に新しいイベントとして認識します。

レスポンス設定

JSON Path

マッピング前に API レスポンスからネストされた値を抽出する JSON Path を指定します。例えば、レスポンスが:

{
  "status": "ok",
  "data": {
    "temperature": 12.5,
    "humidity": 80
  }
}

JSON Path を data に設定すると、{ "temperature": 12.5, "humidity": 80 } がマッピング入力として抽出されます。

空にするとレスポンスオブジェクト全体が使われます。

重複排除モード

モード	動作
Full	成功するたびにイベントを作成
Diff	マッピング結果の SHA-256 ハッシュを前回と比較。マッピング出力が変化した場合のみイベントを作成。

Diff モードは、ほとんど同じデータを返す API（天気、システムステータスなど）に便利です。ハッシュはマッピング結果に対して計算されるため、マッピングしていないフィールド（タイムスタンプやリクエスト ID など）が変わっても重複イベントは発生しません。

Endpoint ライフサイクル

ステータスフロー

ステータス	バッジ	動作
テスト	アンバー	Test Now 可能、タイマー未起動、イベント作成なし
アクティブ	グリーン	スケジュールに従いタイマー実行、成功ごとにイベント作成
無効	グレー	タイマー停止、リクエストなし

利用可能な遷移:

• テスト → 正式上線（アクティブ）または無効化
• アクティブ → 一時停止（無効）またはテストモード（テスト）
• 無効 → 有効化（アクティブ）

連続失敗による自動無効化

poll が 5 回連続で失敗すると自動的に無効化されます。poll カードにエラーメッセージが表示されます。原因（URL、認証情報、CORS）を修正してから手動で再有効化してください。

CORS に関する注意事項

リクエストはブラウザから発信されるため、CORS ポリシーの対象となります:

ターゲット	CORS の挙動	状況
localhost / LAN	通常 CORS 制限なし	動作する
公開 API（CoinGecko、OpenWeatherMap 等）	多くが Access-Control-Allow-Origin: * を設定	通常動作する
制限付き API	ブラウザリクエストをブロックする可能性	動作しない場合あり

Test Now リクエストが CORS エラーで失敗した場合、エラーメッセージに表示されます。回避策:

1. 代わりに Webhook を使用 — API が Webhook コールバックをサポートしている場合
2. CORS プロキシを使用 — CORS ヘッダーを追加する軽量なローカルプロキシ
3. ブラウザ拡張機能 — 拡張機能は CORS 制限の対象外

インポート / エクスポート

poll 設定は JSON としてエクスポートし、別のデバイスやブラウザにインポートできます。

• エクスポート: 現在のエージェントのすべての poll 設定を含む JSON ファイルをダウンロード。ランタイム状態（最終ポーリング時刻、エラー）は除去、認証情報は含まれます。
• インポート: JSON ファイルを読み込み、新しい poll エントリを作成。インポートされた poll はテストモードで開始。既存の poll は上書きされません。

注意

エクスポートファイルには平文の認証情報が含まれます。安全に保管してください。

制限

制限	値
最小ポーリング間隔	1 秒
最大ポーリング間隔	86400 秒（24 時間）
エージェントあたりの最大 poll 数	10
リクエストタイムアウト	10 秒
最大レスポンスサイズ（マッピング用）	50 KB
最大イベントペイロードサイズ	10 KB

Webhook と API Poll の比較

	Webhook（プッシュ）	API Poll（プル）
方向	外部 → サーバー	ブラウザ → 外部 → ブラウザ → サーバー
トリガー	外部システムが POST 送信	ブラウザタイマー（setInterval）
稼働条件	サーバー稼働中（常時）	ブラウザ/Electron が開いている時
設定の保存先	サーバー（D1 データベース）	ブラウザ（IndexedDB）
認証情報	サーバーが送信元を検証	ブラウザが外部 API に送信
localhost	到達不可	ネイティブに到達可能
クロスデバイス	自動同期	インポート/エクスポート JSON
マッピング	同じテンプレートエンジン	同じテンプレートエンジン
サーバー変更	Webhook テーブル + ルート	なし

関連

• Webhook — プッシュ型イベント取り込み
• イベントストリームの概念