文档

报告 CLI 命令

生成报告并按邮件定时发送,查看并校验审计日志,查询播放证据:播放次数、合计和完整度。

这里的每个命令都按 CLI 参考所述运行:全局标志、JSON 输出、退出代码、修订和重试。

报告

reports show KIND 生成报告(fleet_health、uptime、publishing、alerts、alert_log 或 proof_of_play),加上 --format csv、xlsx 或 pdf 以及 --output FILE 即写入文件;reports subscriptions 按排程通过电子邮件向项目成员发送报告;project export DIR 写入项目数据及各部分的结果。 报告与导出对每一项都有说明。

reports list#

列出报告类型及每种类型接受的筛选条件。

reports list

无参数。

screenrig reports list

返回 data.items,每项含报告的 kind、title、description 及其接受的筛选条件(params),此外还有文件 formats。

reports show#

将一份报告生成为行,或写入 CSV、XLSX 或 PDF 文件。

reports show <kind> [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--group-by folder|screen|tag]
    [--folder-id ID [--direct]] [--tag TAG] [--campaign-id ID] [--advertiser NAME]
    [--format json|csv|xlsx|pdf] [--output FILE]
参数类型必填默认备注
<kind>string是无fleet_health、uptime、publishing、alerts、alert_log 或 proof_of_play。
--fromstring否提前 29 天 --to第一个 UTC 日(含),格式为 YYYY-MM-DD。
--tostring否今天最后一个 UTC 日(含);最多在 --from 之后 366 天。
--group-bystring否folder一行代表什么:folder、screen 或 tag。
--folder-idstring否无仅限此屏幕文件夹及其中的全部内容。
--directboolean否关闭与 --folder-id 一起使用:仅文件夹中直接包含的屏幕(--group-by screen),或该文件夹及其子文件夹。
--tagstring否无仅限带有此标签的屏幕。
--campaign-idstring否无proof_of_play:一个直接广告活动。
--advertiserstring否无proof_of_play:此广告主或赞助商的广告活动,按完整名称匹配,不区分大小写。
--formatstring否jsonjson、csv、xlsx 或 pdf。
--output路径否./KIND.FORMAT使用 --format csv、xlsx 或 pdf 时写入的文件。默认文件名为用连字符书写的报告类型(如 ./fleet-health.pdf),指定 --to 时会加上该日期(如 ./fleet-health-2026-10-28.pdf)。
screenrig reports show fleet_health --group-by screen --from 2026-10-01 --to 2026-10-28
screenrig reports show proof_of_play --advertiser "Acme Corp" --format pdf --output acme-proof-of-play.pdf

JSON 返回 data.columns、data.rows、data.totals 和 data.notes;文件夹报告的行带有用于大纲的 id、parent_id 和 depth,其第一行是整个项目。文件会返回其路径、字节数和 SHA-256。分页报告会完整写入,最多 50000 行(否则为 data.truncated)。proof_of_play 需要在自己的屏幕上出售广告时间的项目。具有 reports 能力的只读访问即可。

reports subscriptions#

按计划通过电子邮件向项目成员发送报告。

reports subscriptions list
reports subscriptions show <id>
reports subscriptions create --name NAME --kind KIND --format pdf|xlsx|csv
    --recipients MEMBERS --cadence daily|weekly|monthly [--weekday DAY]
    [--day-of-month N] [--hour N] [--timezone ZONE] [--filter NAME=VALUE]
reports subscriptions update <id> [--name NAME] [--format pdf|xlsx|csv]
    [--recipients MEMBERS] [--filter NAME=VALUE] [--cadence daily|weekly|monthly]
    [--weekday DAY] [--day-of-month N] [--hour N] [--timezone ZONE]
    [--pause | --resume] [--expect-rev REVISION]
reports subscriptions delete <id>
reports subscriptions send <id>
参数类型必填默认备注
<id>string是无订阅的 rsub_ ID,来自 reports subscriptions list。
--namestring创建时无最多 100 个字符。
--kindstring创建时无reports show 的类型:fleet_health、uptime、publishing、alerts、alert_log 或 proof_of_play。永不更改。
--formatstring创建时无附件格式:pdf、xlsx 或 csv。
--recipientsstring创建时无最多 25 位项目成员,以逗号分隔:用户 ID、成员的电子邮件地址或 owner。update 会替换收件人。
--filterstring否无以 NAME=VALUE 形式给出的报告筛选条件,例如 group_by=screen、folder_id=sfd_ID、tag=Lobby 或 advertiser=Acme;可重复。update 会替换这些筛选条件。
--cadencestring创建时无daily、weekly 或 monthly。
--weekdaystring否monday每周运行:monday 到 sunday。
--day-of-monthinteger否1每月运行:日期,1 到 28。
--hourinteger否0时区内一天中的小时,0 到 23。
--timezonestring否UTC形如 America/Los_Angeles 的 IANA 时区。
--pauseboolean否关闭仅 update:恢复前不发送任何内容。不能与 --resume 同时使用。
--resumeboolean否关闭仅 update:从下一次运行起恢复发送。
--expect-revinteger否无仅 update:除非订阅处于此修订版,否则失败。
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_01EXAMPLEPERSON0000
screenrig reports subscriptions update rsub_01EXAMPLESUB0000000000 --pause

每次运行以 UTC 日覆盖其之前的时段:昨天、之前七天或上个月。收件人必须是项目成员,离开的成员不再收到报告。update 至少需要一项更改。send 立即发送报告,覆盖此刻运行会覆盖的时段,不移动计划,并返回该订阅,包括此次发送的 last_status 和 last_error。失败的运行会重试,并显示为 last_status failed 及 last_error;超过 8 MiB 的 PDF 或 XLSX 附件不会发送。一个组织在其所有项目中最多有 50 个订阅。读取需要 project 能力和只读访问;创建、更改、删除和发送需要管理访问。

审计日志

audit list|show|head|verify|export 读取项目的审计日志:audit list 按操作者、来源、资源、操作和字段搜索配置变更,audit show 显示一个条目及每个已更改字段的变更前和变更后,audit head 显示需保存为锚点的链头,audit verify 重新计算链(可选择对照锚点),在无法验证时以退出码 13 结束,audit export 将筛选后的日志写成 CSV、XLSX 或 PDF 文件。审计日志说明了每一项。

audit list#

按从新到旧的顺序列出审计条目。

audit list [--actor ID] [--actor-kind KIND] [--source SOURCE] [--resource-type TYPE]
    [--resource-id ID] [--action CODE] [--field POINTER] [--since TIME] [--until TIME]
    [--limit N] [--after CURSOR]
参数类型必填默认备注
--actorstring否无仅此人员、代理或服务客户端(按其 ID)所做的更改。
--actor-kindstring否无person、agent、service_client、staff 或 system。
--sourcestring否无更改所经由的界面:dashboard、api、cli、device、webhook 或 system。
--resource-typestring否无仅对此类资源的更改,如 screen、playlist、webhook 或 member。
--resource-idstring否无仅对此资源的更改。
--actionstring否无形如 screen.update 的操作代码,或以 * 结尾的前缀,如 playlist.*。
--fieldstring否无仅触及此成员或其下级成员的更改,以 JSON Pointer 指定,如 /label。
--sincestring否无仅此 RFC 3339 时刻及之后的更改,如 2026-10-01T00:00:00Z。
--untilstring否无仅此 RFC 3339 时刻之前的更改。
--limitinteger否50每页条目数,1 到 200。
--afterstring否无上一页的 data.next_cursor。
screenrig audit list --resource-type screen --resource-id scr_01EXAMPLESCREEN00000000
screenrig audit list --action 'playlist.*' --source cli --limit 20

按从新到旧返回 data.items,每条带有 actor(kind、id、name)、source、action、resource(type、id、name)和 changes,其中每项含 path(指向资源的 JSON Pointer)、before 和 after;凭证在前后两侧都显示为 (redacted)。条目链入后数秒内会出现 seq 和 hash。最后一页的 data.next_cursor 为 null。具有 project 能力的只读访问即可。

audit show#

显示一个审计条目及每个已更改字段的更改前和更改后。

audit show <id>
参数类型必填默认备注
<id>string是无条目的 aud_ ID,来自 audit list。
screenrig audit show aud_01EXAMPLEENTRY0000000000

返回该条目,包含每个已更改字段的 path、before 和 after、谁通过哪个入口做出了更改,以及链入后它在链中的位置。

audit head#

显示需保存为锚点的审计链头。

audit head

无参数。

screenrig audit head

以 SEQ:HASH 的形式打印最后一个已链入的条目、链开始处的保留下限,以及等待链入的条目数。请保存链头:之后 audit verify --anchor SEQ:HASH 可证明历史未被重写或截断。

audit verify#

重新计算审计哈希链,并报告任何不匹配之处。

audit verify [--from-seq N] [--limit N] [--anchor SEQ:HASH]
参数类型必填默认备注
--from-seqinteger否保留的最旧条目要检查的第一个链位置。
--limitinteger否5000本次调用要检查的条目数,最多 5000。
--anchorstring否无您保存的链头 SEQ:HASH:同时证明直至该链头的历史未被更改。
screenrig audit verify --anchor 128:3f2c0b6e9a4d81c7f5e0a2b4c6d8e0f1a3b5c7d9e1f30415263748596a7b8c9d

在 data.problems 中按条目报告 hash_mismatch、prev_mismatch、gap、head_mismatch、anchor_mismatch 或 floor_mismatch。链无法验证时以退出码 13 结束,且 data.ok 为 false;data.next_seq 用于继续验证更长的链。

audit export#

将筛选后的审计日志写成 CSV、XLSX 或 PDF 文件。

audit export --format csv|xlsx|pdf [--output FILE]
    [--actor ID] [--actor-kind KIND] [--source SOURCE] [--resource-type TYPE]
    [--resource-id ID] [--action CODE] [--field POINTER] [--since TIME] [--until TIME]
参数类型必填默认备注
--formatstring是无csv、xlsx 或 pdf。
--output路径否./audit-log.FORMAT要写入的文件。指定 --until 时,默认名称会加上该日期,如 ./audit-log-2026-10-01.csv。
--actor, --actor-kind, --source, --resource-type, --resource-id, --action, --field, --since, --untilstring否无audit list 的筛选条件。不带 --since 时,文件涵盖最近 30 天。
screenrig audit export --format csv --output audit.csv
screenrig audit export --format pdf --resource-type playlist --output playlist-changes.pdf

每个已更改字段写一行,按从旧到新,最多 50000 行(否则为 data.truncated),文件中包含链头和保留下限,并返回其路径、字节数和 SHA-256。

播放

播放证据有四种形式。playback plays 读取屏幕上每次可见的图像、视频或应用开始,每次一行,按 received_at 由旧到新排序:为报告或广告商提供播放证明。playback list 读取每日总计,每个屏幕、媒体对象和 UTC 天一行。playback totals 读取每个 UTC 天的播放计数,或排名最繁忙的屏幕或媒体。playback completeness 读取播放器编号的播放中有多少到达了 screenRIG,以及播放在哪里丢失。

每个播放命令都接受 --format json|csv|xlsx|pdf 和 --output FILE,控制台导出相同的文件。默认的 json 是命令信封,并拒绝 --output;其他格式会写入文件。playback plays 和 playback list 流式输出各自的 CSV,--output - 将其发送到 stdout 而不是信封。其他所有文件都在服务器上渲染并保存到文件路径。xlsx 或 pdf 对 playback plays 最多包含 50,000 行,对 playback list 最多包含 200 行。每个命令都会指明其默认文件。

播放记录保留以满足计划的事件保留要求,至少30天。

问题代码退出含义
invalid_request8播放范围超过 31 天,日范围超过命令的上限,或过滤器格式错误。CLI 在发送任何内容前就拒绝其中大部分(退出码 2)。
rate_limited7每个组织每分钟 30 次的播放导出配额已用尽。请等待retry_after_seconds。

智能体请求:每个 JSON 页是一个智能体请求,因此 --all 每页发出一个请求。CSV 导出对整个范围是一个请求。每个播放记录请求(JSON 页、CSV、XLSX 或 PDF)以及 playback list 的每次 CSV 导出,还会消耗播放导出预算。playback totals 和 playback completeness 各是一个智能体请求,不消耗该预算。

playback plays#

读取每次播放记录,每个可见启动一行。

playback plays [--from TIME] [--to TIME] [--screen-id ID] [--media-id ID] [--tag TAG] [--cursor CURSOR] [--limit N] [--all]
playback plays --format csv|xlsx|pdf [--output FILE] [--from TIME] [--to TIME] [--screen-id ID] [--media-id ID] [--tag TAG]
参数类型必填默认备注
--from TIMEstring否提前 24 小时 --toreceived_at 的包含上限:带秒和偏移的 RFC 3339 时间点,now,或类似 7d、12h 或 30m 的时长。
--to TIMEstring否现在独占绑定,形式相同。范围最多31天。
--screen-id IDstring否每个屏幕一个 scr_ 屏幕。
--media-id IDstring否每个对象一个 med_ 媒体对象。
--tag TAGstring否每个屏幕播放接收时屏幕携带的标签:1 到 32 个字母或数字。
--cursor CURSORstring否范围的开始上一页的 next_cursor(pc_…),使用相同的筛选条件。
--limit Ninteger否200每个 JSON 页的行数,1 到 1000。仅限 JSON:--format csv 会拒绝它。
--allboolean否关闭跟随游标至范围末尾,每页 1000 行,除非 --limit 另有说明,最多 50 页。仅限 JSON:--format csv 会拒绝它。
--format FORMATstring否jsonjson、csv、xlsx 或 pdf。csv 流式输出整个范围;xlsx 和 pdf 包含其前 50,000 行。
--output FILE路径否./playback-plays.csv,./plays.xlsx 或 ./plays.pdf要写入的文件;需要指定文件格式。使用 --format csv 时,- 将 CSV 写入 stdout 而不是信封。
screenrig playback plays --from 7d --tag Lobby --all
screenrig playback plays --format csv --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z --output september-plays.csv
screenrig playback plays --format xlsx --from 7d --tag Lobby --output lobby-plays.xlsx

CLI 将两个边界时间标准化为 UTC 并在每次请求中发送;data.from 和 data.to 会回显它们。最新的 5 秒数据会被暂缓,直到稳定,因此播放在接收后约 5 秒出现,data.to 报告该有效结束时间。应用播放带有 release_id 和空的 media_id。JSON 在 data.items 中返回一页,带有 data.next_cursor,data.next.argv 是下一页的精确命令。--all 会提前停止,并带有 data.next 和警告,在达到页面上限(playback_plays_truncated)或导出预算用尽(playback_export_rate_limited)时触发,而不是继续发送请求直至被拒绝。

CSV 遵循 RFC 4180,固定表头行为 screen_id,playlist_id,page_id,primitive_id,media_id,primitive,started_at,received_at,manifest_revision,playlist_revision,时间为 RFC 3339 UTC。primitive_id 和 started_at 为空,除非播放器报告了它们。以 =、+、-、@、制表符或回车开头的单元格会加前导 ',防止电子表格计算。CLI 通过同目录下的私有临时文件写入,流正常结束后才替换现有文件。--timeout 是无进度超时限制,默认 60000 毫秒无字节传输,不限制总时长。信封报告 path、bytes、rows、sha256、content_type、from、to 和 last_received_at;CSV 不进入信封。使用 --output - 时,CSV 输出到 stdout,不打印信封。

如果流中途失败,命令以非零退出且不写入目标文件。已接收的完整行保留在 FILE.partial(该文件已存在时为 FILE.partial-2 等),error.next 从最后一个 received_at 起将范围的其余部分导出到未使用的 FILE-rest.csv。在该瞬间接收的行同时出现在两者中,合并时去掉重复项。使用 --output - 时,不完整的 CSV 保留在 stdout,错误和 next 命令输出到 stderr。

xlsx 和 pdf 在服务器上渲染,并以同样方式通过私有临时文件保存。信封报告 path、bytes、sha256、content_type 和 format,文件包含该范围的前 50,000 行。

playback list#

读取该项目的每日播放总数,最新日期优先。

playback list [--screen-id ID] [--media-id ID] [--day YYYY-MM-DD | --day-from YYYY-MM-DD --day-to YYYY-MM-DD]
              [--format json|csv|xlsx|pdf] [--output FILE]
参数类型必填默认备注
--screen-id IDstring否每个屏幕必须以 scr_ 开头。
--media-id IDstring否每个对象必须以 med_ 开头。
--day YYYY-MM-DDstring否每天一个 UTC 日历日。不适用于 --day-from 或 --day-to。
--day-from YYYY-MM-DDstring否无含首尾的 UTC 日期范围的第一天。与 --day-to 一起时范围最长为 366 天。CSV 默认设为 --day-to 之前 30 天。不适用于 --day。
--day-to YYYY-MM-DDstring否无该范围的最后一天。CSV 默认为今天。不适用于 --day。
--format FORMATstring否jsonjson、csv、xlsx 或 pdf。csv 流式输出每个匹配的行;未指定范围时为截至今天的 31 天。xlsx 和 pdf 包含与 JSON 列表相同的行。
--output FILE路径否./playback-aggregates.csv,./play-aggregates.xlsx 或 ./play-aggregates.pdf要写入的文件;需要指定文件格式。使用 --format csv 时,- 将 CSV 写入 stdout 而不是信封。
screenrig playback list --screen-id scr_01EXAMPLESCREEN00000000 --day 2026-08-14
screenrig playback list --format csv --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback list --format pdf --day-from 2026-09-01 --day-to 2026-09-30 --output september.pdf

每块屏幕、每个媒体对象、每个 UTC 日一行。筛选器选择调用方自己的行。JSON 在 data.items 中最多返回 200 行,最新的日期在前;每日合计大约每 10 分钟刷新一次,playback plays 显示更新的开始记录。CSV 表头行是 screen_id,media_id,filename,primitive,day,play_count,last_page_id,last_manifest_revision,first_started_at,last_started_at。CSV 是一个请求,写法与播放记录 CSV 相同,其结果报告 path、bytes、rows、sha256 和 content_type;xlsx 或 pdf 结果报告 path、bytes、sha256、content_type 和 format。失败的每日导出不会保留任何内容;请重新运行。

playback totals#

读取每个 UTC 日的播放次数,或排名最繁忙的屏幕或媒体。

playback totals [--by day|screen|media|screen_day] [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD]
                [--screen-id ID | --media-id ID] [--top N] [--format json|csv|xlsx|pdf] [--output FILE]
参数类型必填默认备注
--by GROUPINGstring否dayday 每个 UTC 日返回一行。screen 或 media 排名最繁忙的。screen_day 返回最活跃屏幕的每日序列。
--day-from YYYY-MM-DDstring否提前 29 天 --day-to首个 UTC 天(含)。
--day-to YYYY-MM-DDstring否今天最后的UTC日,含当日。
--screen-id IDstring否每个屏幕使用 --by day 时,仅计数此屏幕。不适用于 --media-id。
--media-id IDstring否每个对象使用 --by day 时,仅计数此媒体对象。不适用于 --screen-id。
--top Ninteger否10排名的行,1 到 100;使用 --by screen_day 时为 1 到 10。需要 --by;不适用于 --by day。
--format FORMATstring否jsonjson、csv、xlsx 或 pdf。其余三种将相同的行写入文件。
--output FILE路径否./play-totals.csv,./play-totals.xlsx 或 ./play-totals.pdf用 --format csv、xlsx 或 pdf 写入的文件。仅限文件路径:- 会被拒绝。
screenrig playback totals
screenrig playback totals --day-from 2026-09-01 --day-to 2026-09-30 --screen-id scr_01EXAMPLESCREEN00000000
screenrig playback totals --by screen --top 5
screenrig playback totals --by media --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback totals --by screen_day --top 3
screenrig playback totals --by screen --top 10 --format xlsx --output busiest-screens.xlsx

计数来自每日汇总,滞后于摄取最多约 21 分钟;playback plays 显示较新开始。day 返回 data.days,screen 和 media 返回 data.screens 和 data.media,screen_day 返回 data.screen_days。日期序列最多 366 天(使用 --screen-id 或 --media-id 时为 92 天),排名最多 92。data.truncated 是 true,当窗口过大导致只保留每片段最佳键时。文件格式会将服务器的文件写入 --output,其信封报告 path、bytes、sha256、content_type 和 format。

playback completeness#

按 UTC 天读取播放器编号的播放中有多少到达了 screenRIG,以及播放丢失的缺口。

playback completeness [--day-from YYYY-MM-DD] [--day-to YYYY-MM-DD] [--screen-id ID] [--limit N]
                      [--format json|csv|xlsx|pdf] [--output FILE]
参数类型必填默认备注
--day-from YYYY-MM-DDstring否提前 29 天 --day-to起始 UTC 日期,包含该日。区间最长为 92 天。
--day-to YYYY-MM-DDstring否今天最后的UTC日,含当日。
--screen-id IDstring否每个屏幕仅此屏幕。必须以 scr_ 开头。
--limit Ninteger否100要列出的缺口数,按最新在前排列,1 到 500。
--format FORMATstring否jsonjson、csv、xlsx 或 pdf。其余三种将相同的行写入文件。
--output FILE路径否./play-completeness.csv,./play-completeness.xlsx 或 ./play-completeness.pdf用 --format csv、xlsx 或 pdf 写入的文件。仅限文件路径:- 会被拒绝。
screenrig playback completeness
screenrig playback completeness --day-from 2026-09-01 --day-to 2026-09-30
screenrig playback completeness --screen-id scr_01EXAMPLESCREEN00000000 --limit 20
screenrig playback completeness --format pdf --output completeness.pdf

每次媒体开始都带有一个编号,因此屏幕已播放但从未送达的播放(例如离线播放并超出其 24 小时报告队列的播放)会留下缺口。data.completeness 是窗口内 data.measured_plays 除以 data.measured_plays 与 data.missing_plays 之和,取值 0 到 1,两者都未测量时为 null:没有编号的播放(来自不为播放编号的播放器,或来自它们开始编号之前的播放)不参与测量。data.days 给出每个有数据的 UTC 日的相同三项数字,由旧到新排列,缺口计入其后一次播放所在的那一天。data.gaps 按由新到旧列出每个缺口,附带 screen_id、day、from 和 to(两侧播放的开始时间)以及 missing_plays;--limit 设置其上限,更多缺口存在时 data.truncated 为 true。关闭的屏幕不产生播放,也不留下缺口。汇总每 10 分钟刷新一次。计为一次计量 API 请求;播放导出预算不适用。文件格式会将服务器的文件写入 --output,其信封报告 path、bytes、sha256、content_type 和 format。

其他命令组