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 を使って重複排除

​
推奨の読み順

For comprehensive understanding, read in this order:
  1. Task Lifecycle - Understand status values and transitions
  2. Async Operations - Handle different operation types
  3. Webhooks - Implement push notifications reliably
  4. Error Handling - Handle failures gracefully
  5. Orchestrator Design - Put it all together

​
次のステップ