Skip to main content
このセクションでは、AdCP と連携する堅牢な本番対応システムを構築するためのパターンとベストプラクティスを紹介します。

​
コアパターン

Task Lifecycle

ステータス値、状態遷移、ポーリングパターン。あらゆる AdCP 操作の基盤。

Async Operations

同期・非同期・対話的オペレーションの扱い。タイムアウト、進捗管理、完了処理。

Webhooks

プッシュ通知の設計、信頼性パターン、サーキットブレーカー、冪等なハンドラー。

Error Handling

エラー分類、標準エラーコード、復旧戦略、リトライロジック。

​
システム設計

Security

AdCP 連携のセキュリティ考慮。Webhook 検証、リプレイ防止、アクセス制御。

Orchestrator Design

ステートマシン設計、オペレーション追跡、永続化パターン、再同期。

​
対象読者

このセクションは主に オーケストレーターを構築する開発者 を想定しています。たとえば次のようなシステムを作る場合です:
  • 複数の AdCP オペレーションを同時に管理します
  • 再起動に耐え、状態を復元する必要があります
  • 長時間（数時間〜数日）の処理を扱います
  • 高い信頼性と監査性が求められます
単発の AdCP 呼び出しを行うシンプルな統合であれば、Integration セクションで十分です。

​
主要な設計原則

​
1. 非同期を前提に

AdCP の処理時間は秒〜日単位になり得ます。すべてを非同期として設計してください:
  • オペレーション状態を永続化します
  • オーケストレーター再起動に耐える
  • 適切なタイムアウト処理を実装します

​
2. ステータス駆動のロジック

すべてのレスポンスに status フィールドがあります。これを起点にロジックを組み立てます: 
switch (response.status) {
  case 'completed': return processResults(response);
  case 'working': return pollForUpdates(response.task_id);
  case 'input-required': return promptUser(response.message);
  case 'failed': return handleError(response);
}

​
3. Webhook とポーリングの併用

Webhook のみに依存しないでください:
  • 即時通知のため Webhook を設定
  • バックアップとしてポーリングを実装
  • 信頼性のためサーキットブレーカーを使用

​
4. オペレーションの冪等性

すべてのオペレーションを冪等に保ちます:
  • 新規作成前に既存オペレーションを確認
  • 重複した Webhook 配信を許容して処理
  • イベント ID を使って重複排除

​
推奨の読み順

体系的に理解するため、以下の順に読むとよい:
  1. Task Lifecycle - ステータス値と遷移を理解します
  2. Async Operations - 異なるオペレーション種別に対応します
  3. Webhooks - プッシュ通知を確実に実装します
  4. Error Handling - 障害を適切に処理します
  5. Orchestrator Design - すべてをまとめ上げる

​
次のステップ