通知 CLI コマンド

操作

アップロードと公開は操作として実行されます。media upload、media replace、app uploadはデフォルトで自分の操作を待ちます。これらのコマンドは、--no-waitで実行したままにした操作を完了させるために使います。

operations show <id>

screenrig operations show op_01EXAMPLEOPERATION00000

operations wait <id> [--timeout MS] [--poll-ms MS]

screenrig operations wait op_01EXAMPLEOPERATION00000

operations cancel <id>

screenrig operations cancel op_01EXAMPLEOPERATION00000

イベント

プロジェクトのイベントログはプロジェクトとフリートの動作を記録します。公開されたリリースはapplication.publishedを追加し、screenrig.emit(code)を呼ぶアプリは自身のイベントを追加します。これはスクリーンで実行された最も直接的な証拠です。

プレゼンスはログにもあります。screen.offlineはスクリーンが60秒間オフラインの後に1回書き込まれ、screen.onlineは復帰時に書き込まれます。60秒以内の再接続はどちらも書き込みません。screen.offlineはdetails.offline_sinceを含み、スクリーンが以前オンラインだった場合はdetails.last_online_atも含みます。screen.onlineはdetails.last_online_atを含み、スクリーンが復帰前にオフラインだった場合はdetails.offline_atも含みます。すべてのscreen.*イベントと同様に、これらはリッスンストリームで無料で配信されるため、エージェントはevents followを開いたままにしてフリートを監視できます。

Playerのコンテンツ更新はscreen.manifest_changed、screen.manifest_activated、screen.manifest_upgradeとして届き、そのdetailsにはmanifest_revision、state、および存在する場合はcodeとattemptが含まれます。failedのアップグレードは重大度がエラーで、retrying、blocked、partialは警告です。

events list [--after CURSOR] [--limit N] [--type TYPE] [--source project|log] [--screen-id ID] [--playlist-id ID] [--app-id ID]

screenrig events list --limit 25
screenrig events list --type application.event --screen-id scr_SCREEN
screenrig events list --playlist-id pl_PLAYLIST
screenrig events list --source log --screen-id scr_SCREEN

events follow [--after CURSOR] [--timeout MS] [--type TYPE]

screenrig events follow

通知

通知は、画面の状態が変わったときに、人または別のシステムに知らせます。メール通知は各宛先にメールを送り、Webhook 通知は署名付き HTTPS POST を送り、Slack・Teams・PagerDuty・Telegram の通知はチャットまたはページャーにメッセージを投稿します。1 つの組織で作成できるのは、すべてのチャネルとすべてのプロジェクトを合わせて最大 50 件で、すべてのプロジェクトは、画面が 10 分間オフラインのときにオーナーへ送るメール 1 件から始まります。

通知は、指定した条件を監視します：

条件は --hold 分（デフォルトは10分）続くと通知されます。そのため、短時間で再接続した場合は通知されません。それより前に終了した場合は何も送信されず、通知メッセージの送信後に終了した場合は、解決済みの通知メッセージが続きます。crashing は即時に送信されます。待機時間中に誰かがそのスクリーンのアラートを確認済みにするかスヌーズした場合や、ミュートがそのスクリーンに適用されている場合も、通知メッセージはスキップされます。--tag は通知をそのタグを持つスクリーンに限定します。指定しない場合は、すべてのスクリーンが対象になります。

各通知には重大度があります。発生通知は、screen_offline では error、それ以外のすべての条件では warning、解決通知とテストは info です。--min-severity LEVEL（info、warning、error）は、そのレベルを下回る発生通知を作成せず、解決通知は対応する発生通知に従います。--severity CONDITION=LEVEL は繰り返し指定でき、この通知について1つの条件のレベルを、たとえば --severity not_playing=error のように設定します。--min-severity の判定に使われます。Teams と PagerDuty は常にこのレベルを表示し、メール、Slack、Telegram の本文には、通知が --min-severity または --severity を設定しているときに重大度が記載され、Webhook の本文には severity が含まれます。

--active-hours SPEC は、必須の --timezone ZONE で解釈される週間ウィンドウ内でのみ、発生通知を送信します。SPEC は DAYS HH:MM-HH:MM（たとえば "Mon-Fri 08:00-22:00"）で、最大16回まで繰り返せます。デフォルトの --outside-hours hold では、時間外に送信期限を迎えた通知は次のウィンドウまで待機し、その時点で条件がまだ成り立っていれば送信されるため、先に条件が解消すれば何も送信されません。drop では、通知は outside_hours としてスキップされ、notifications deliveries に一覧されます。送信済みの発生通知に対する解決通知は常に送信され、crashing は他の条件と同様に時間帯に従い、スヌーズが最初に確認され、notifications test は時間帯、重大度、オーディエンスを無視します。

--audience FILE（インライン JSON、ファイル、または標準入力を表す -）は、キャンペーンのオーディエンスのルールでスクリーンを選択します。たとえば、両方のタグを持つスクリーンには {"all":[{"tag":"level2"},{"tag":"overhead"}]} を使います。--all-tags TAG と --any-tag TAG は、タグの all ルールと any ルールの短縮形で、--tag はいずれかのタグを意味します。--tag、--any-tag、--all-tags、--audience は互いに排他です。

loop_stalled、glass_blank、glass_frozen は、screenRIG が受け取った再生レポートとスクリーンショットから導く判定で、判定できないものは対象外です。オフラインの画面、ディスプレイがオフの画面、テイクオーバー中または一時停止中の画面、静止画 1 枚やビデオウォールを表示している画面、再生番号を送らない Player の画面などです。これらの状態にあると判定していた画面を screenRIG が判定しなくなると、アラートは閉じますが、画面が回復した様子が確認されたわけではないため、メール、Slack、Teams、Telegram は解決通知を送りません。PagerDuty は引き続きインシデントを解決します。

source_failed と source_stale はプロジェクトのスクリーンではなくデータソースを監視します。通知にはデータソースの名前とそのページへのリンクが含まれ、--tag がデータソースに一致することはありません。

card_data_stale はスクリーンではなくカードを監視します。カードのデータは、書き込み側のスケジュールに合わせた有効期限を付けて書き込みます (card data put --ttl 30m)。更新するジョブやエージェントが止まると、データは期限切れになり、カードはそれを表示するすべてのスクリーンで空白になり、この条件でお知らせします。通知にはカード名とデータが期限切れになった時刻が含まれ、そのカードを配置したページのページエディターへのリンクが付きます。データソースのドキュメントはここでは通知されません (source_stale が対象です)。どのスクリーンにも表示されていないカード、有効期限なしで書き込まれたデータ、削除されたデータも通知されません。--tag はカードには一致しません。

reach_dropped と group_empty は、スクリーンではなくキャンペーンを監視します。通知には、キャンペーン名と、以前と現在に到達したスクリーン、または空のタグやフォルダーが記載され、キャンペーンのカレンダーへのリンクが付きます。キャンペーンはプロジェクトに属するため、--tag、--any-tag、--all-tags、--audience がこの 2 つを制限することはありません。--min-severity、--severity、--active-hours、--hold は他の条件と同様に適用され、どちらもデフォルトで warning です。--reach-drop-screens N と --reach-drop-percent P は、キャンペーンの公開時に到達していたスクリーンのうち、N 台以上かつ P パーセント以上が減少した場合にのみ reach_dropped 通知を送ります。減少は両方を満たす必要があり、設定がなければどの減少でも通知されます。これらには --conditions の reach_dropped が必要です。キャンペーンの空のタグやフォルダーは 1 つずつ別の通知になり、notifications deliveries では audience_group（tag:Lobby または folder:sfd_…）として表示されます。空のグループをオーディエンスから外す公開を行うと、PagerDuty のインシデントと Webhook のアラートはクローズされますが、復旧メールやチャットメッセージは送信されません。

メールは各受信者の検証済みアドレスに送信されます。約2分以内に送信対象となったものは、受信者ごとに1通にまとめられ、各スクリーンへのリンクとダッシュボード内の通知へのリンクが付きます。受信者は owner（通知メッセージの送信時にプロジェクトを所有している人）と、プロジェクトメンバーのユーザーIDです。検証済みアドレスがない受信者や、プロジェクトを離れた受信者はスキップされます。通知メールとスクリーン通知メッセージは無料です。

各メールには、その受信者専用の配信停止リンクがあります。メールアプリの配信停止ボタンと、フッターのリンクです。このリンクを開いて操作すると、その通知のメールがその 1 人にだけ届かなくなります。サインインは不要で、開いたページには Resubscribe ボタンがあります。ほかの受信者には影響せず、その人は受信者に残ります。notifications show は unsubscribed で配信を停止した人を表示し、notifications resubscribe はその人にメールを再開します。メールを送る相手がいない通知は no_recipients としてスキップされます。

Webhook通知は各通知メッセージをJSONとしてPOSTします。検証は 配信を検証 の説明に従って行います。--events を指定すると、生のプロジェクトイベントも発生と同時にPOSTします。これらの配信は Webhook の説明に従って計測されます。

Slack、Teams、PagerDuty、Telegram の通知は、障害ごと、画面ごと、または画面のグループごとに 1 件のメッセージを投稿します。内容は、画面、変更内容、開始時刻、プロジェクト、画面へのリンク、そしてオフラインだった画面が復帰したときは、その時点で分かっていれば推定原因です。最初のメッセージが送信されると復旧メッセージが続き、PagerDuty では最初のメッセージが開いたインシデントを解決します。認証情報は 1 回だけ指定します（--slack は受信 Webhook の URL、--teams は Workflows Webhook の URL、--pagerduty は Events API v2 のルーティングキー、--telegram はボットトークンと --telegram-chat を受け取ります）。認証情報は封印されて二度と表示されず、destination_hint にはマスクされた末尾だけが表示されます。- を指定すると stdin の 1 行から読み取るため、シェルの履歴に残りません。投稿に失敗した場合は 24 時間再試行され、72 時間失敗し続けた通知は無効になります。

3 台以上のスクリーンが互いに 5 分以内に同じ条件に入り、ネットワーク、ロケーション、モデル、Player のバージョン、またはタグを共有しているとき、メール、Slack、Teams、PagerDuty、Telegram の通知は、スクリーンごとではなく、まとめて 1 件の通知を送り、グループの最後のスクリーンが復旧したときに 1 件の通知でそのグループを伝えます。ほかの各スクリーンの通知は grouped としてスキップされます。Webhook は引き続きスクリーンごとに 1 件の通知を送ります。

通知とその配信の閲覧には閲覧のみのアクセスが必要で、通知の作成・変更・テスト・削除、シークレットのローテーション、ユーザーの再購読には管理アクセスが必要です。

notifications create (--email RECIPIENTS | --webhook URL | --slack URL | --teams URL | --pagerduty KEY
                      | --telegram TOKEN --telegram-chat CHAT_ID) [--conditions LIST] [--events TYPES]
                     [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE] [--hold MINUTES]
                     [--min-severity LEVEL] [--severity CONDITION=LEVEL]... [--active-hours SPEC]...
                     [--timezone ZONE] [--outside-hours hold|drop] [--reach-drop-screens N] [--reach-drop-percent P]
                     [--description TEXT] [--disabled]

screenrig notifications create --email owner --conditions screen_offline,display_disconnected --tag Lobby

screenrig notifications create --webhook https://hooks.example.com/screenrig --conditions screen_offline,crashing

screenrig notifications create --slack - --conditions screen_offline,crashing < slack-url.txt

notifications list

screenrig notifications list

notifications show <id>

screenrig notifications show ntf_01EXAMPLENOTICE00000

notifications update <id> [--email RECIPIENTS | --url URL | --destination VALUE] [--telegram-chat CHAT_ID]
                          [--conditions LIST | --clear-conditions]
                          [--events TYPES | --clear-events] [--tag TAG... | --any-tag TAG... | --all-tags TAG... | --audience FILE | --all-screens]
                          [--hold MINUTES] [--min-severity LEVEL | --clear-min-severity]
                          [--severity CONDITION=LEVEL]... [--clear-severity]
                          [--active-hours SPEC]... [--timezone ZONE] [--outside-hours hold|drop] [--clear-active-hours]
                          [--reach-drop-screens N] [--reach-drop-percent P] [--clear-reach-drop]
                          [--description TEXT | --clear-description] [--enable | --disable]
                          [--snooze WHEN] [--expect-rev REVISION]

screenrig notifications update ntf_01EXAMPLENOTICE00000 --snooze 2h

notifications delete <id> [--expect-rev REVISION]

screenrig notifications delete ntf_01EXAMPLENOTICE00000

notifications rotate-secret <id> [--expect-rev REVISION]

screenrig notifications rotate-secret whk_01EXAMPLEWEBHOOK00000

notifications test <id>

screenrig notifications test ntf_01EXAMPLENOTICE00000

notifications resubscribe <id> --user USER_ID

screenrig notifications resubscribe ntf_01EXAMPLENOTICE00000 --user usr_01EXAMPLEPERSON0000

notifications deliveries <id> [--before CURSOR] [--limit N]

screenrig notifications deliveries ntf_01EXAMPLENOTICE00000 --limit 20

配信を検証

スクリーン通知メッセージの本文は JSON です：type（alert.opened または alert.resolved）、id（配信ID）、notification_id、project_id、condition、screen（id と name）、since（条件が始まった時刻）、at（待機時間を満たした時刻、または解消した時刻）、event_id、severity（info、warning、error のいずれか。alert.opened では条件のレベル、alert.resolved では info）。screen_offline の alert.resolved には likely_cause（device_restart、app_crash、app_restart、network、platform のいずれか）も含まれ、原因が不明な間は null です。データソース、キャンペーン、カードの場合は screen がそれを指し、キャンペーンの通知には、reach_dropped では reach（published と current のスクリーン数）、group_empty では audience_group（kind は tag または folder、および value）が追加されます。--events からの生のイベントは、events list が返すものと同じ JSON オブジェクトです。ヘッダーは ScreenRig-Webhook-Id（通知ID）、ScreenRig-Event-Id（リトライ間で安定：通知メッセージでは配信ID、イベントではイベントカーソル）、ScreenRig-Signature: t=<unix seconds>,v1=<hex> で、v1 は "<t>.<raw body>" に対する HMAC-SHA256 でシークレット文字列をキーにしています。JSON を解析する前に生のバイトで計算し、定数時間で比較し、古い t を拒否し、ScreenRig-Event-Id で重複排除します。これは、配信が少なくとも1回で順不同のためです。10秒以内に 2xx で応答し、リダイレクトは追いません。

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body bytes (Buffer) exactly as received.
function verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof signatureHeader !== "string" || !signatureHeader) return false;
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

アラート

アラートは、1つのスクリーンで続いている1つの問題です。スクリーンが、スクリーンの通知の条件（screen_offline、display_disconnected、running_hot、on_battery、storage_full、content_stuck、not_playing、loop_stalled、glass_blank、glass_frozen）のいずれかに入ると、通知が監視しているかどうかにかかわらずアラートが発生し、条件が終了すると解決されます。スクリーンには条件ごとに最大1件の未解決アラートがあります。クラッシュの急増、データソース、カード、キャンペーンは通知メッセージであり、アラートにはなりません。screenRIG が送った再起動（screen reboot または再起動スケジュール）で再起動中のスクリーンは、再起動が完了するか、送信から10分が経つまで、screen_offline と display_disconnected のアラートを発生させません。その時点でも条件が続いていれば、アラートが発生します。alerts list で現在未解決のものを確認できます。

未解決のアラートは、誰かが確認済みにするかスヌーズするか、ミュートがそのスクリーンに適用されるまで、対応が必要な状態です。確認済みにすると、誰かが対応中であることを示します。アラートは未解決のままですが、誰がいつ確認したかが記録され、解決するまで対応は不要になります。スヌーズは最長30日先までの時刻まで確認済みにすることで、その時刻にアラートがまだ未解決なら再び対応が必要になります。後から行った確認やスヌーズは、前のものを置き換えます。アラートが確認済みまたはスヌーズ中の間は、そのアラートに関する通知のうち待機時間中の通知メッセージはスキップされます。

ミュートはメンテナンス用です。スクリーン、タグ、またはその両方を指定し、最長30日先までの時刻で終了します。ミュートは、スクリーンのIDが指定されているか、指定されたタグを持っている間、そのスクリーンに適用されます。そのため、後からタグを付けたスクリーンも対象になり、タグを外したスクリーンは対象外になります。ミュート中のスクリーンのアラートも発生・解決されますが、muted と表示され、対応が必要になることはなく、すべての通知がそのアラートの通知メッセージをスキップします。1つの組織で有効なミュートは、すべてのプロジェクトを合わせて最大50件です。

alerts list の counts.attention は、ダッシュボードがアラートの横に表示する数です。アラートの発生・解決・確認では screen.alert_opened、screen.alert_resolved、screen.alert_acknowledged が、ミュートの作成・終了では alert_mute.created、alert_mute.deleted がプロジェクトのイベントログに追加されます。これらは、すべての screen.* イベントと同様に、リッスンストリームと Webhook で無料です。解決済みのアラートは、プランのイベント保持期間の間、一覧に残ります。アラートとミュートの閲覧には閲覧のみのアクセスが必要で、確認済みにする・スヌーズ・ミュート・ミュート解除には管理アクセスが必要です。

alerts list [--state open|resolved|all] [--screen-id ID] [--before CURSOR] [--limit N]
            [--format json|csv|xlsx|pdf] [--output FILE]

screenrig alerts list

screenrig alerts list --state all --screen-id scr_01EXAMPLESCREEN00000000

screenrig alerts list --state all --format csv --output alerts.csv

alerts show <id>

screenrig alerts show alr_01EXAMPLEALERT000000

alerts ack <id>

screenrig alerts ack alr_01EXAMPLEALERT000000

alerts snooze <id> (--for DURATION | --until TIME)

screenrig alerts snooze alr_01EXAMPLEALERT000000 --for 4h

alerts mute [--screen-id ID]... [--tag TAG]... (--for DURATION | --until TIME) [--note TEXT]

screenrig alerts mute --tag Lobby --for 2h --note "Rewiring the lobby displays"

alerts mutes

screenrig alerts mutes

alerts unmute <mute-id>

screenrig alerts unmute amt_01EXAMPLEMUTE0000000

Webhook

Webhook はこのプロジェクト自身のイベントを署名付きPOSTとして運用中のHTTPSエンドポイントに送信するため、一致するイベントでエージェント、ボット、または独自サービスを起動できます。一致する各イベントは、events list が返すものと同じJSONオブジェクトとして到着します。Webhook は元の形の 通知 です。組織の通知上限50件に含まれ、notifications list に表示されます。新しい作業には、メールとスクリーン通知メッセージも送信する notifications を使用します。

配信の試行は無料で、組織の1時間あたりのエージェントリクエスト上限に数えられません。

webhooks create --url URL --event-types TYPES [--description TEXT] [--disabled]
webhooks list
webhooks show <id>
webhooks update <id> [--url URL] [--event-types TYPES] [--description TEXT | --clear-description]
                     [--enable | --disable] [--expect-rev REVISION]
webhooks delete <id> [--expect-rev REVISION]
webhooks rotate-secret <id> [--expect-rev REVISION]
webhooks test <id>
webhooks deliveries <id> [--before CURSOR] [--limit N]

組織にすでに50個の通知がある場合、webhooks create は webhook_limit_reached（終了コード5）で応答し、notifications create は notification_limit_reached で応答します。拒否されたURLは、どちらも webhook_url_rejected（終了コード8）です。

--url には、ホストがパブリックインターネットアドレスのみに解決するポート 443 または 8443 の https URL を指定します。検証は notifications create と同様です。認証情報または # フラグメントを含む URL は、ローカルで終了コード 2 で拒否されます。--event-types には、screen.online のような完全一致の種別、または .* で終わる screen.* のようなプレフィックスを、カンマ区切りで 1 から 32 個指定します。--description は 200 文字までです。--disabled は無効な状態で Webhook を作成します。webhooks update --enable は失敗状態を解除して現在のイベントから開始するため、無効だった間のものは送信されず、--disable は保留中の配信を webhook_disabled で失敗させます。--expect-rev はリビジョンを保護します（revision_conflict、終了コード 6）。

webhooks create と webhooks rotate-secret は、署名シークレットを data.secret に一度だけ出力し、警告 webhook_secret_shown_once を付けます。中断またはあいまいな呼び出しの後は、24 時間以内に同じコマンドを再実行すると、同じ応答が返ります。配信は、Webhook の作成後に発生した最初のイベントから始まります。webhooks test は、この Webhook だけに webhook.test 配信を 1 件キューに入れます。無効な Webhook でも動作し、再試行なしで 1 回だけ試行され、ほかの配信と同様に計測され、組織ごとに 1 分あたり 20 件までに制限されます（rate_limited、終了コード 7）。webhooks list はこのプロジェクトの Webhook 通知を古い順に表示し、閲覧のみの認証情報では各 url が空になり url_redacted が true になります。webhooks deliveries はログを最新のイベントから読み取り、1 ページあたり 1〜200 行（既定は 50）で、next_cursor（whc1_…）を --before として渡します。各行の state は pending、succeeded、failed のいずれかで、last_status と固定の last_error クラスを持ちます。配信の検証は 配信を検証 のとおりです。