アラートトリガー API

プロジェクトのトリガー（CAP とオーバーレイ）を古い順に最大 20 件一覧します。各トリガーには受信 url、username、最新のアラートまたはオーバーレイの状態が含まれます。シークレットはここでは返されません。

CAPアラートトリガーを作成します：緊急通知システム（Everbridge、Rave、Alertus、IPAWSリレーおよびその他のCAP 1.2送信者）がアラートを投稿する1つの受信URLで、HTTP Basic認証情報を使用します。

回答はパスワードが表示される唯一の場所です（回転回答と共に）：送信システムにすぐに保存してください。targetはタグ（アラート到着時にそれを持つすべてのアクティブスクリーン）または最大500のscreen_idsです。

アラートはデフォルトプレイリストを持つすべてのターゲットスクリーンに対し、アラートの<expires>まで、そうでなければdefault_for_seconds（60～604800、デフォルト3600）まで適用します。POST /api/triggers/{id}/cap.を参照してください。組織は、すべてのプロジェクトを合わせて最大20のトリガーを持ちます（trigger_limit_reached）。trigger.createdを追加します。

完全一致する Idempotency-Key の正確な再試行は24時間同じ回答（パスワード含む）を返します。

任意の pull は、プラットフォームがトリガーのために読み取る CAP ソースを追加します（CapPull を参照）。受信 url はそのまま使えます。kind overlay を指定すると、代わりに 2 つ目の種類を作成します。任意のシステム（Home Assistant、カメラ、アラートツール）が短い文言を送る受信 url（POST /api/triggers/{id}/overlay）で、アラートが続く間、対象画面に再生中の内容の上のストリップ（overlay.show bar、下端または上端）または引き継ぎ（overlay.show takeover）として表示されます。TriggerOverlay を参照してください。

signing が true の場合、応答には署名シークレットも1回だけ含まれます。verify は、ベンダー自身の署名 (GitHub、Stripe、Shopify、Slack、Linear、Vercel、Asana、または任意の HMAC 送信元) を、パスワードの代わりに送信の認証に使います。パスワードも並行して使えます。signing とは併用できず、そのシークレットは封印して保存され、返されることはなく、ヒントだけが返されます。handshake は、URL が応答するベンダーのハンドシェイクを指定します (Microsoft Graph、monday.com、Trello、Azure Event Grid。verify slack と asana は自分のハンドシェイクに応答します)。

オーバーレイの保持時間は10〜604800秒です（デフォルト600）。セレクターが保護されたスクリーンに及ぶトリガーは protected_target（409）で、スクリーン保護の読み取りに失敗した場合は dependency_unavailable（500、同じリクエストを再試行）です。トリガーは、スクリーンに限定された呼び出し元は利用できません。

最新のアラート、またはオーバーレイトリガーの場合は有効なアラート（新しい順、先頭が表示中）、配信の件数、保留中の処理の有無を含むトリガー。until を過ぎたアラートは ended_reason expired の終了として読み取られます。

URL とシークレットを変えずにトリガーを変更します: label、target、default_for_seconds、CAP トリガーの pull（null で削除）、オーバーレイトリガーの overlay.edge、style（スタイル全体を置き換え、null で消去）、mapping（null で削除）、enabled、signing、verify（null で削除。シークレットなしの場合、ベンダーが同じなら保存済みのものを保持します）、handshake（null で削除）。

無効にしたオーバーレイトリガーは、送信元に誤ったシークレットと同じ 404 を返します。署名を有効にすると、署名シークレットがこの応答で一度だけ返されます。ストリップは新しい対象スクリーンと端に置き直されます。引き継ぎトリガーの新しい対象は、次に始まるアラートから適用されます。trigger.updated を details.changed 付きで追加します。If-Match でリビジョンを確認します。

すべての更新は、トリガーが持つことになる対象（新しい対象、なければ保存済みの対象）に対して確認されます。保護されたスクリーンに及ぶ対象は、どのメンバーが変更しても protected_target（409）で、スクリーン保護の読み取りに失敗した場合は dependency_unavailable（500、同じリクエストを再試行）です。

トリガーを削除します。URL はすぐに使えなくなり、アラートのプレイリストと静止画（オーバーレイトリガーではストリップ、プレイリスト、カード）も削除されます。アラートを表示中、またはまだ終了処理中のトリガーは resource_conflict で拒否されるので、先に終了してください。trigger.deleted を追加します。If-Match でリビジョンを確認します。

トリガーのパスワードを置き換え、新しいものを一度だけ返します。古いパスワードはすぐに使えなくなるので、送信元のシステムを更新してください。ボディで signing を true にすると、代わりにオーバーレイトリガーの署名シークレットを置き換えて一度だけ返します（署名しないトリガーでは 400 invalid_request）。trigger.updated を details.rotated 付きで追加します。

If-Match でリビジョンを確認します。

トリガーのスクリーンに1分間のエクササイズアラート（黄色のEXERCISEバナー付きの青いカード）を表示します。これは受信したアラートとまったく同じで、送信システムなしでターゲティングとスクリーンを確認できます。トリガーがアラートを表示している間はresource_conflictが拒否されるため、テストは実際のアラートを置き換えません。

同じ Idempotency-Key での完全な再試行は outcome duplicate を返します。オーバーレイトリガーはアラート screenrig-test（label Test、title Test overlay）を 1 分間表示し、TriggerOverlayReceipt を返します。

トリガーのアラートを終了し（ended_reason cleared）、設定したテイクオーバーを解除します。別のテイクオーバーに置き換えられたスクリーンはそのままにします。アクティブなアラートがないトリガーは変更なしを返します。trigger.alert_receivedにoutcome endedを追加します。

オーバーレイトリガーでは、ボディで 1 つのアラート（alert_id）を指定できます。指定しないとすべてのアラートが終了し、最後のアラートが終わるとストリップが消えるか、引き継ぎが終了します。

緊急通知システムが 1 件の CAP 1.2 アラートを投稿する URL（任意の XML コンテンツタイプ、最大 256 KiB）。トリガー自身の HTTP Basic 認証を使います：ユーザー名はトリガー ID、パスワードは create または rotate で返されたもの。

ステータスが Actual または Exercise で msgType が Alert のメッセージは、デフォルトプレイリストのすべての対象スクリーンに全画面カード（見出し、イベント、説明、指示、送信者）を表示します。Extreme、Severe、または無指定のときは赤、Moderate はアンバー、Minor は青。Exercise は黄色の EXERCISE バナーを追加します。表示期間は <expires> まで、そうでなければ default_for_seconds まで、最大7日間です。

表示中のアラートを参照する更新は、その場で再描画し、<expires> が変更されたときにテイクオーバーを移動します。参照するキャンセルや responseType が AllClear のメッセージはそれを終了し、設定したテイクオーバーをクリアします。トリガーは一つのアラートを表示します：新しいアラートが表示中のものを置き換えます。

テスト、システム、ドラフトメッセージ、AckとError、既に期限切れのアラート、表示されていないアラートのキャンセルは無視されます。同じ送信者と識別子の2回は重複です。応答は結果を示す受領書で、スクリーンはその直後に書き込まれます（alert.screens.pending）。

テイクオーバーはスクリーン制御のレート制限を回避し、課金や拒否はされません。trigger.alert_received を追加します。

外部システム（Home Assistant、カメラ、ドアセンサー、アラートツール、または自社の Webhook に署名するベンダー）が、トリガーのスクリーンに短い文言を表示させるために送信する URL。トリガー自身のシークレットを Authorization ヘッダー（Bearer <secret>）で、または、ユーザー名をトリガー ID にした HTTP Basic で認証します。

トリガーを verify 付きで作成した場合、そのベンダー自身のヘッダー (WebhookVerifyWrite を参照) に有効な署名があれば、シークレットの代わりに送信が認証されます。シークレットも並行して使えます。

トリガーが署名する場合は、ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> も必須で、t はサーバーの時計から 5 分以内でなければなりません。

不明なトリガー、CAP トリガー、間違っているか欠けているシークレットや署名、古いタイムスタンプ、無効なトリガー、そしてすべての GET は、同じ 404 not_found で応答します。プロジェクトは理由をトリガーの配信ログで確認できます。

ベンダーのハンドシェイク用に設定されたトリガーは、認証情報が求められる前に、そのハンドシェイクであるリクエストに最初に応答します。Slack の url_verification チャレンジ (署名付き)、Microsoft Graph の validationToken、Asana の X-Hook-Secret (イベントの署名シークレットとして封印して保持)、monday.com の challenge、Azure Event Grid の SubscriptionValidationEvent、Trello の HEAD チェック (この URL の head 操作) です。

ハンドシェイクはアラートを変更せず、課金されず、レート予算も消費せず、結果 handshake で配信ログに記録されます。

本文は最大 256 KiB で、JSON、application/x-www-form-urlencoded、または multipart/form-data です (各テキストフィールドは body.<field>、ファイルパートは無視され、配信ログに数えられます)。mapping がある場合は、テンプレートが body と query からリクエストを組み立てます。alert_id でアラートを指定します。有効な ID の送信は別のアラートを重ねずにそのアラートを更新し、最後に開始したアラートが表示されます。

発生または更新のたびに、その送信から duration の間アラートを保持します（10〜604800 秒、または 10s, 5m, 2h, 1d, until_cleared。省略時はトリガーの既定値）。送信を続けるセンサーはオーバーレイを維持できます。

clear が true の送信、または終わりを意味する state（off, closed, clear, cleared, resolved, ok, normal, inactive, ended）は、その ID のアラートを終了します。ID がなければすべてのアラートを終了します。発生または更新は課金対象の API リクエスト 1 回で、解除は無料で、残高を理由に拒否されることはありません。

Idempotency-Key（8〜200 文字）を付けると、送信元の再試行に 24 時間は最初の受領証が返ります。1 トリガーあたり 1 分間に最大 120 件の送信。

Trello が新しい Webhook に対して行うチェックです。ハンドシェイクが trello のトリガーには本文なしの 200 で応答し、それ以外のあらゆるトリガー、アドレス、リクエストには 1 つの 404 not_found で応答するため、リンクプレビューは何も知ることができません。何も書き込まず、課金されず、レート予算も消費しません。応答したチェックは、結果 handshake で配信ログに記録されます。

すべての GET は 404 で応答し、何も読み取りません。

過去 7 日間のオーバーレイトリガーへの送信です。新しい順に最大 100 件で、それぞれの到着時刻、結果 (shown、updated、unchanged、ended、ignored、refused、invalid、handshake)、拒否または無効になった理由 (credentials、signature、signature_missing、signature_invalid、timestamp_missing、timestamp_stale、secret_pending、handshake_invalid、disabled、body、mapping、field、rate_limited、payment_required、internal)、ステータス、サイズ、マルチパートの送信に含まれていたファイルパートの数 (無視されます)、リクエスト ID が含まれます。

ボディ、ヘッダー、認証情報は保持しません。CAP トリガーには配信がありません。