キャンペーン API

プロジェクトのキャンペーンを優先順位順（最大100件）に一覧表示します。解決時にもこの順序で読み取られます。reserved はすべてのキャンペーンに含まれます。

スクリーンに限定された呼び出し元（docs/screen-scope.md）には、すべてのキャンペーンが表示されますが、editable が true になるのは、対象全体がスコープ内にあり、呼び出し元が再生内容を変更できる場合のみです（タグのリーフとルートの全スクリーンルールは該当しません。all ルールには含まれる子が1つ、any ルールにはすべての子が必要です）。

キャンペーンを作成します。from、until、windows がスクリーンのタイムゾーンで成り立つ間（screenrig.schedule/v1。常時にするには 3 つとも省略）、audience のすべてのスクリーンが playlist_id に切り替わり、成り立たなくなると元に戻ります。

スクリーンは、テイクオーバー、次に優先順位（priority の高い順、次に作成が新しい順）で最初に適用されるキャンペーン、次にプレイリストスケジュール、最後にデフォルトプレイリストの順でプレイリストを決定します。キャンペーンはデフォルトプレイリストを持つスクリーンにのみ適用され、from、until、windows を持つキャンペーンにはスクリーンのタイムゾーンが必要です。

プレイリストは存在し、承認済みである必要があります（playlist_not_approved）。スクリーンは1分以内に切り替わります。GET /api/campaigns/{id}/screens は各スクリーンの状況を示します。組織のキャンペーンは、すべてのプロジェクトを合わせて最大100件です（campaign_limit_reached）。

campaign.created を追加します。reserved が true の場合はキャンペーンを確保し、設定できるのは承認できる人だけです（エージェント、サービスクライアント、その他の場合は reserved_item）。campaign.reserved_changed が追加されます。

スクリーンに限定された呼び出し元（docs/screen-scope.md）がキャンペーンを作成できるのは、スコープ内の対象に対してのみです（folder と screen_id のリーフのみ。タグや全スクリーンは不可）。それ以外は outside_screen_scope となり、作成できるのは承認できる人としてのみです（approver_required）。

対象が保護されたスクリーンに及ぶキャンペーンは、すべてのアクセスレベルで protected_change レビューとなり、2人目の承認者が決定します（202 pending_review）。reserved が true の場合は保護フォルダー、新規キャンペーン（下書き）で paused が true の場合はスケジュールの変更管理であり、どちらも Enterprise プランに含まれます。プランにこの機能が含まれていないプロジェクトは feature_not_in_plan（402）で拒否されます。

キャンペーンの書き込みで変わる内容を、書き込まずに返します。id がある場合、body はそのキャンペーンの PATCH 本文で、ない場合は新しいキャンペーンの POST 本文です。本文は書き込みと同じ方法で検査されます (オーディエンスのルール、ウィンドウ、未承認のプレイリスト、プロジェクトにないスクリーンフォルダー)。

応答には、スタックにキャンペーンが加わるスクリーンと、キャンペーンを失うスクリーン (count と、先頭 500 件のスクリーン ID) が一覧表示されます。さらに、古いオーディエンスと新しいオーディエンスのスクリーンのスケジュールカレンダーが、from から to まで (デフォルト: 現在から 1 週間。最大 93 日) の現状 (before) と変更後 (after) の両方で、GET /api/schedule/calendar と同じ方法でグループ化されて含まれます。

一時停止中のキャンペーンはどのスタックにも載らないため、公開するとそのオーディエンスが加わります。キャンペーンをスクリーンのスタックに載せたままにする編集では、加わるものも失われるものもなく、カレンダーに表示されます。読み取りアクセス: 何も書き込まれません。

1つのキャンペーン。reserved は常に含まれ、editable はスクリーンに限定された呼び出し元に含まれます（listCampaigns を参照）。

本文で設定されたメンバーを変更します。null を指定すると from、until、windows が消去されます。paused true はすべてのスクリーンでキャンペーンを停止し、false は再開します。一時停止中のキャンペーンは下書きです。どのスクリーンのスタックにも載らず、一時停止のままにする書き込みではどのスクリーンも再解決されません。

テストのために公開するには、paused false で、オーディエンスがテストフォルダーまたは少数のスクリーンである、この PATCH を使います。続いて POST /api/campaigns/{id}/promote がそのオーディエンスを本番のキャンペーンにコピーします。古いオーディエンスと新しいオーディエンスのすべてのスクリーンが 1 分以内に再解決されます。campaign.updated を追加します。If-Match がリビジョンを保護します。

書き込みはそれぞれキャンペーンの履歴に保存されます (GET /api/campaigns/{id}/revisions)。campaign.updated。If-Match がリビジョンを保護します。reserved は reserved フラグを設定または解除します (予約済みキャンペーンを変更、一時停止、または予約解除できるのは承認できるユーザーだけで、それ以外は reserved_item)。フラグが切り替わると campaign.reserved_changed を追加します。

スクリーンに限定された呼び出し元（docs/screen-scope.md）が変更できるのは、保存済みの対象と新しい対象の両方がスコープ内にあるキャンペーンのみです（outside_screen_scope。そうでない場合、そのキャンペーンは読み取り専用です）。

保護されたスクリーンに及ぶキャンペーンは protected_change レビューとなり、2人目の承認者が決定します（202 pending_review）。確保されていないキャンペーンで reserved が true の場合は保護フォルダーであり、Enterprise プランに含まれます。プランにこの機能が含まれていないプロジェクトは feature_not_in_plan（402）で拒否されます。

キャンペーンの一時停止と再開、および確保済みキャンペーンの編集と解除は、すべてのプランで利用できます。

キャンペーンとそのリビジョン履歴を削除します。キャンペーンを表示していたすべてのスクリーンは、1 分以内にキャンペーンがない場合の表示に戻ります。campaign.deleted を追加します。If-Match がリビジョンを保護します。予約済みキャンペーンを削除できるのは、承認できるユーザーだけです (reserved_item)。

スクリーンに限定された呼び出し元（docs/screen-scope.md）がキャンペーンを削除できるのは、対象がスコープ内にある場合のみです（outside_screen_scope）。保護されたスクリーンに及ぶキャンペーンは protected_change レビューとなり、2人目の承認者が決定します（202 pending_review）。

キャンペーンのリビジョン (新しい順): ユーザー、エージェント、またはスケジュールインポートによる書き込み (作成、更新、昇格、復元) のたびに保存されたキャンペーンの状態で、変更の種類と変更者が含まれます。

履歴は、リビジョン履歴が最初に記録されたときにキャンペーンが保持していたリビジョンから始まります。次の書き込みまで、一覧にはそのリビジョンだけが change baseline として含まれます。履歴に paused false のリビジョンがないキャンペーンは下書きです。リビジョンはキャンペーンが存在する間は保持され、キャンペーンとともに消えます。

1 ページあたり最大 50 件。続きがある間は next_cursor が返り、最後のページでは null です。

PATCH と同じ書き込みで以前のリビジョンをコピーして先に進め、再び現在のリビジョンにします。name、playlist、audience、rule、placement、priority、paused が新しいリビジョンになり (change restored、restored_from はコピー元のリビジョン)、更新と同じ検査が行われます (プレイリストが存在し、承認済みである必要があります)。キャンペーンが一時停止中で一時停止のままの場合を除き、古いオーディエンスと新しいオーディエンスのすべてのスクリーンが再解決されます。

以前のリビジョンはそのまま残ります。If-Match は必須で、現在のリビジョンを指定します (ない場合は invalid_request、古い場合は revision_conflict)。内容が現在の内容と同じリビジョンは何も変更せず、現在のキャンペーンを返します。PATCH と同じアクセスです。

テストを公開します。テスト公開とは、paused false で、オーディエンスがテストフォルダーまたは少数のスクリーンである下書きの PATCH です。promote は、revision (下書き自身の一時停止中のリビジョン) のオーディエンスを 1 回の書き込みでキャンペーンにコピーし (change promoted、restored_from はコピー元のリビジョン)、古いオーディエンスと新しいオーディエンスのすべてのスクリーンが再解決されます。

そのリビジョンが一時停止中でなかった場合は下書きではないため、またキャンペーンが現在一時停止中の場合は昇格するテストがないため、拒否されます (invalid_request で、revision を示します)。If-Match は必須で、現在のリビジョンを指定します。オーディエンスが現在のものと同じリビジョンは何も変更しません。PATCH と同じアクセスです。

昇格はスケジュールの変更管理であり、Enterprise プランに含まれます。プランにこの機能が含まれていないプロジェクトは feature_not_in_plan（402）で拒否されます。リビジョン履歴、復元、プレビューはすべてのプランで利用できます。

キャンペーンの到達範囲。counts は audience 内のすべてのライブスクリーンを対象とし（audience、続いてステータスごとの件数）、items はそれらのスクリーンを screen id 順に 1 ページ分、各スクリーンでのキャンペーンの状況とともに示します（CampaignStatus を参照）。

スクリーンに限定された呼び出し元（docs/screen-scope.md）には、スコープ内の対象スクリーンのみが表示・集計されます。件数とページングはその集合を対象とします。