screenRIG
登录开始使用

文档

报告与导出

报告读取项目的汇总数据：可用性汇总、告警历史、屏幕状态和直接广告活动的投放，从不扫描原始事件。每个报告都是一张表，可输出为 JSON、CSV、XLSX 或 PDF，任何报告都可以按排程通过电子邮件发送。

按文件夹和标签的汇总

fleet_health、uptime、publishing 和 alerts 按文件夹、屏幕或标签，在含首尾的 UTC 日期范围内汇总设备群。文件夹行统计其中及所有子文件夹内的每块屏幕，第一行是整个项目。标签是第二种分组：屏幕在其带有的每个标签中各计一次。

报告每行表示的内容
fleet_health屏幕数、当前在线、可用性、未解决告警、周期内发生的告警、高温、显示器断开、崩溃中，以及正在播放最新内容的屏幕数
uptime在线和离线小时数、可用性和已记录覆盖率
publishing内容最新、内容更新中、内容需要关注和无内容的屏幕数
alerts当前未解决的告警和周期内发生的告警，按条件统计
alert_log周期内每个告警一行：屏幕、条件、开始和结束时间以及确认人
proof_of_play某赞助商或广告主的直接广告活动按活动、媒体和屏幕统计的播放次数及合计

GET /api/reports/{kind} 生成报告。from 和 to 为 UTC 日期（默认最近 30 天）；group_by 为 folder（默认）、screen 或 tag；folder_id 将报告限定为某个文件夹及其内部全部内容，加上 direct=true 则限定为该文件夹及其子文件夹，按屏幕分组时限定为直接位于其中的屏幕；tag 只保留带有该标签的屏幕。文件夹行带有 id、parent_id 和 depth，客户端可据此从行中绘制层级。可用性是在线时间占已记录时间的比例，已记录覆盖率表示屏幕在周期内报告过状态的比例。

控制台的健康页面按屏幕文件夹呈现这些汇总：每个文件夹可展开其子文件夹和屏幕，每块屏幕可进入其健康标签页。

CSV、XLSX 和 PDF

每个报告路由都接受 format=csv、xlsx 或 pdf，并以包含相同行的附件响应：新的报告、GET /api/uptime/daily、GET /api/screens/{id}/uptime、GET /api/screens/{id}/health/history、GET /api/health/trend、GET /api/alerts、GET /api/playback、GET /api/playback/plays、GET /api/playback/totals、GET /api/playback/completeness、广告投放、填充和支出报告以及直接广告活动的报告。分页的报告会完整写出，最多 50,000 行；truncated 表示其仅包含前面的行。

XLSX 文件是单个工作表，标题和周期位于冻结表头之上，数字保持为数字，合计以粗体显示。PDF 是简洁的对账单，含 screenRIG 名称、所属项目、标题和周期、每页重复表头的表格、合计和页码，可直接发送。CSV 以列标签开头，并会对电子表格可能当作公式执行的文本单元格进行无害化处理。

screenrig reports show fleet_health --group-by folder --format pdf --output fleet-health.pdf
screenrig reports show proof_of_play --advertiser "Acme Corp" --from 2026-10-01 --to 2026-10-31 --format pdf --output acme.pdf
screenrig project uptime --format xlsx --output uptime.xlsx
screenrig alerts list --state all --format csv --output alerts.csv

面向赞助商或广告主的播放证明

proof_of_play 汇总项目直接广告活动的播放次数。当屏幕报告媒体已在屏幕上播放完毕时计为一次播放。用 campaign_id 指定一个活动，或用 advertiser（完整名称，不区分大小写）指定某赞助商或广告主的全部活动。每一行是一个活动、一个媒体文件和一块屏幕，含播放次数、播放小时数、首日和末日，屏幕带有受众估计时还含估计曝光量。PDF 即可发送的对账单。

邮件排程

报告订阅指明报告类型及其筛选条件、频率、文件格式和接收的项目成员。POST /api/report-subscriptions 创建订阅；每个组织跨其所有项目最多 50 个（report_subscription_limit_reached）。

成员含义
kindfleet_health、uptime、publishing、alerts、alert_log 或 proof_of_play
filters报告的日期以外的筛选条件：group_by、folder_id、direct、tag、campaign_id、advertiser
schedulecadence daily、weekly（weekday）或 monthly（day_of_month，1 到 28）、hour 0 到 23 以及 IANA timezone
formatpdf、xlsx 或 csv，作为邮件附件
recipients项目成员，用 user_id 或成员的电子邮件地址指定

每次运行覆盖其之前的周期（按 UTC 日）：每日运行为前一天，每周运行为前七天，每月运行为前一个整月，均按排程所在时区的日历计算。收件人是项目成员，每次发送都会重新核对：其他人在写入订阅时即被拒绝，离开项目或邮箱地址未验证的成员将不再收到。附件最大 8 MiB。

失败的运行会在 15 分钟、1 小时和 4 小时后重试，之后等待下一次排程。订阅会显示 last_status（delivered 或 failed）、last_error、上次运行覆盖的日期以及 next_run_at。POST /api/report-subscriptions/{id}/send 会立即为现在运行所覆盖的周期发送，不改变排程，并返回订阅及本次发送的结果。

screenrig reports subscriptions create --name "Monday fleet health" --kind fleet_health \
  --cadence weekly --weekday monday --hour 7 --timezone America/Los_Angeles \
  --format pdf --recipients ann@example.com,usr_ID
screenrig reports subscriptions list
screenrig reports subscriptions send rsub_ID

控制台的报告页面在“邮件排程”下提供同样的排程。

导出整个项目

screenrig project export DIR 将项目数据以开放格式写入目录。使用副本进行恢复之前，请检查各部分的结果。

路径包含
export.json格式（screenrig.export/v1）、生成时间、每个分区的结果，以及每个文件的大小和 SHA-256
project.json, tags.json项目及其标签和对应的屏幕
screens/screens.json、folders.json 和 schedules.json（每块屏幕的层级、接管和显示器排程）
playlists/每个播放列表及其所有修订，JSON 格式
campaigns.json, advertising/direct-campaigns.json广告活动和直接广告活动
cards/, sources.json, applications.json, triggers.json卡片及其数据、数据源配置、应用程序元数据和警报触发器
applications/APP_ID/kv.json每个应用的持久化 K/V 条目：base64 值、内容类型、字节数、SHA-256 和修订号
notifications.json, webhooks.json, alert-mutes.json, report-subscriptions.json通知、webhook、静音和排程
media/files/ 和 media/manifest.json原始媒体文件，以及每个文件的 id、名称、类型、大小和 SHA-256
data/播放、播放汇总、每日可用性、按屏幕的可用性和告警的 CSV
log/events.jsonl项目事件日志，每行一个 JSON 事件
log/audit.jsonl, log/audit-head.json审计日志，每行一个 JSON 条目，以及其链头

请将原始应用程序归档与导出一起保存，以便恢复发布版本，包括旧播放列表固定的版本。省略的应用程序内容会显示在应用程序文件部分，并设置 data.complete:false 及 export_application_content_omitted，使用 --no-media 时也一样。重新运行会刷新元数据。

无论使用 --no-media 还是 --since，应用的 K/V 数据都会完整复制。如果读取 K/V 列表或某个值失败，applications 部分会以 export_section_failed 标记为失败，并设置 data.complete:false。请解决读取错误后重新运行，以更新副本。

副本中绝不包含凭据：webhook 的签名密钥和接收地址、通知的聊天或寻呼凭据以及数据源的机密都会被排除（文件保留接收端的来源和机密的名称）。重新运行是安全的：JSON 文件整体重写，已完整的媒体文件会保留，部分下载的文件从已有字节继续。每个媒体文件在保留前都会与项目记录的 SHA-256 核对。--no-media 跳过媒体文件，--since DAY 指定 CSV 数据和事件日志的起始日。每个请求都是计费的 API 请求，媒体下载属于出站流量。