按屏幕文件夹设置权限

谁被限制

• 成员。 项目所有者将成员限定在选定的屏幕文件夹和屏幕。成员照常登录，只能查看和更改自己的屏幕。
• 智能体。 所有者以同样方式限定智能体。智能体的触达范围也不会超过对其负责的人员：其触达范围是自身范围经该人员范围收窄后的结果，因此受限的人员不会通过范围更宽的智能体行事。
• 不受限制。 项目所有者和覆盖整个项目的服务客户端。

限制称为范围。它在每次请求时读取，从不存储在令牌或会话中，因此更改会在此人的下一次请求时生效，无需重新登录。没有范围的调用方处理整个项目，检查不产生任何开销。

文件夹与继承

屏幕文件夹构成层级结构。指定某个文件夹的范围包含该文件夹及其内部每个文件夹中的所有屏幕，并且在文件夹移动时随之移动。

Hotel
  Lobby            <- the lobby manager's scope holds Lobby and Bar
    Bar
  Casino Floor     <- the floor manager's scope holds Casino Floor
  Rooms

• 一个范围最多包含 1,000 个文件夹和 200 个单独屏幕，且两者至少有一个。
• 单个屏幕可以位于任意数量的范围内，文件夹也是如此。
• 写入范围时，ID 必须指向项目中现存的文件夹和屏幕。之后被删除的文件夹或屏幕会留下不授予任何权限的 ID。
• 审批审核的成员限定于文件夹。单个屏幕适用于不审批的成员。
• 一个人要么限定于屏幕，要么是上传者，不能两者兼具：上传者限定于内容，受限成员限定于屏幕。

设置范围

只有项目所有者可以在控制台中设置、更改或结束范围。

1. 打开控制台的访问页面。
2. 在“人员”下打开该成员并使用屏幕。勾选文件夹（包含其内部的所有内容），如果该成员不审批，则添加单个屏幕。保存。
3. 对于智能体，请在“智能体”下打开它，并使用同样的屏幕控件。
4. 若要在人员加入之前限制他们，请把范围加入邀请。

在同一位置移除范围，即可让成员重新拥有整个项目。

设置成员的范围会结束此人带到项目中的智能体，因此不会有任何东西保留它之前被授予的更大触达范围。当此人或其带来的智能体持有项目的有效服务客户端时，范围会被拒绝：请撤销拒绝信息中指出的每个客户端，然后再次设置范围。将项目转让给某位成员会移除该成员的范围。

带范围受邀的成员加入后是不能审批的成员。当他们应为自己的文件夹决定审核时，所有者在同一页面为其开启可批准。

受限人员能做什么、能看到什么

在范围内，受限人员像项目成员一样工作，无论是在控制台、使用 CLI 还是通过 API：

• 屏幕。 读取、健康、播放记录、正常运行时间、截图和实时画面、评论、命令（如重启、清除缓存、识别和更新）、标签、字段、位置、名称、播放列表、播放列表排程、接管、归档和删除。
• 文件夹。 在范围内创建、重命名、移动和删除文件夹，并设置文件夹的默认播放列表。范围所指定的文件夹会保留：只有范围更大的人员才能删除它。
• 移动。 屏幕或文件夹从范围内的一处移动到另一处。来源和目的地都必须在范围内。
• 活动。 创建、更改和删除受众全部在范围内的活动。
• 设备组操作。 按 ID 或范围内的文件夹选择屏幕。
• 新屏幕。 可以审批的受限人员可将屏幕配对或配置到范围内的文件夹。新屏幕会指定其文件夹，因此落在范围之内。
• 备注。 读取和写入关于自己屏幕、关于播放列表以及不针对任何对象的备注。

内容（媒体、播放列表、应用、卡片、卡片数据）仍由成员的角色管理，与任何成员完全相同。

受限人员无法触及任何项目管理功能：成员、邀请、服务客户端、智能体登录、舰队链接、计费、设置、webhook、通知、警报、触发器、排程导入和项目范围的报告都会被拒绝。每项都返回 outside_screen_scope。

活动只能在范围内编辑

所有人都能在列表中看到活动，受限人员只有在整个受众都在其范围内时才能编辑。否则 editable 为 false，该活动对其为只读。

• 范围内的文件夹或屏幕位于范围之内。
• 当每个子项都在范围内时，any 规则即为范围内。
• 当至少有一个子项在范围内时，all 规则即为范围内，因为它是交集。
• 标签规则和针对每个屏幕的规则永远不在范围之内。

不能审批的受限人员

不能审批的受限成员可以读取范围内的所有内容，并运行命令、截图和评论，但只能通过审批人更改播放内容。分配播放列表、排程、接管、活动、文件夹和移动对其返回 approver_required。没有范围的成员不受影响。

范围之外的内容

范围之外的屏幕会从每个列表中隐藏：屏幕列表、文件夹的屏幕、活动屏幕、日历、事件和实时流。文件夹树显示范围内的文件夹及其上级文件夹，为只读且不带屏幕数量，使树有一个根。它们的同级文件夹会被隐藏。

指明范围之外的屏幕、文件夹、选择器或受众的请求会被整体拒绝，绝不会被缩小范围：不写入任何内容。范围之外的 ID 和不存在的 ID 得到相同的答复。

{
  "status": 403,
  "errors": [
    {
      "code": "outside_screen_scope",
      "screen_scope": { "folder_ids": ["sfd_01LOBBY"], "screen_ids": [] },
      "hint": "Ask the project owner to widen the scope, or leave this to a member of the whole project."
    }
  ]
}

screen_scope 给出调用方自身的范围，使调用方知道自己可以使用什么。播放记录、日历和播放器日志需要范围内的一个屏幕（日历也可使用文件夹）。项目范围的健康趋势和每日正常运行时间会被拒绝；单个屏幕的健康历史和正常运行时间仍可使用。

委托管理

给场馆经理分配其文件夹，并让他们自行管理：

1. 所有者把经理限定在场馆的文件夹。
2. 所有者为经理开启可批准。
3. 经理直接在其文件夹中分配播放列表、排程和活动，并决定智能体为这些文件夹提议的审核。

受限的审批人只能决定整个触达范围都在其范围内的审核，审核页面也只列出这些审核。受限的审批人不决定任何广告创意审核。触及范围之外屏幕的审核返回 outside_screen_scope。

组织成员、访客和管理员

一个人最多有一个主组织。以某组织为主组织的人员是该组织的成员。在任何其他组织的项目中，此人是外部人员，即访客，项目的人员列表会标记他们。项目成员身份仍是进入其内容的唯一途径。GET /api/session 报告人员的 organization，GET /api/members 用 external 标记每位访客。

• 成为成员。 组织管理员通过电子邮件邀请某人，接受邀请后，该组织取代其他任何组织成为其主组织。地址位于组织已验证域名下的人员是成员，由单点登录或用户预配管理的人员也是成员。没有主组织的人创建项目后，该项目所属的组织成为其主组织。加入项目绝不会更改主组织。
• 移除成员。 管理员将成员从组织中移除。其主组织被清除，由管理员或邀请授予的项目访问随之结束；由用户预配授予的访问仍归预配管理。被移除的人员即使地址位于已验证域名下，也会保持移出状态，直到收到新的邀请。若此人拥有该组织的某个项目（member_owns_projects），移除会被拒绝：请先转让该项目。由组织的身份提供者管理的人员须在身份提供者处移除（managed_member），管理员则在其管理员席位结束后被移除（organization_admin_member）。

访客策略

组织在组织设置中选择准许哪些人作为访客进入其项目。

策略在人员被添加到项目时生效：发出邀请时、接受邀请时再次生效、通过群组绑定添加时，以及管理员添加某人时。成员和组织自己的管理员绝不会被拒绝。拒绝时的响应为 guest_not_allowed。收紧策略不会移除任何人：人员页面会标记每位该策略不再准入的访客。

媒体库

组织管理员在组织设置中选择一个项目作为组织的媒体库（Premium、Education 和 Enterprise）。组织的其他所有项目随后以只读方式使用该媒体库的媒体、文件夹和播放列表：

• 把其中的媒体放到页面上。
• 用文件夹选择器播放媒体库中的文件夹。标签选择器和 all 选择器只使用项目自己的媒体。
• 为其播放列表排期，并基于其模板创建播放列表。

只有媒体库自己的成员才能修改它们。有屏幕的项目不能用作媒体库，设为媒体库后也无法向其中添加屏幕（library_no_screens）。智能体用 screenrig media list --library、screenrig media folder list --library 和 screenrig playlist list --library 列出媒体库。

组织管理员的职责

管理员对组织的每个项目拥有管理权限，只有在加入项目后才能读取其内容。

• 加入项目。 管理员可以不带范围的审批人身份加入组织的任何项目，已是受限成员时同样可以。此操作记录在审计日志中，并向项目所有者发送电子邮件。再次加入不会有任何变化。
• 更换所有者。 管理员可以将已验证的项目成员或组织的其他成员设为项目所有者，所有者已离开或已停用时同样可以。已加入项目的管理员可以将自己设为所有者。此操作会被记录，并向原所有者和新所有者发送电子邮件。
• 移除项目成员。 管理员可以移除任何不是所有者或自己的成员。此操作会被记录。
• 在其所属成员的项目内，管理员对其他人员拥有所有者的成员管理权限：移除成员、设置谁可以批准、设置屏幕和上传范围、转让所有权，以及绑定 SCIM 群组。

受保护的文件夹

受保护文件夹用于没有任何单个人能更改播放内容的屏幕。可以审批的人员在控制台中为文件夹开启受保护，保护涵盖其中的每个文件夹。智能体和服务客户端从不保护文件夹，智能体只能以提议的形式解除保护：screenrig screen folder update ID --unprotect 会成为由第二位审批人决定的审核。范围受限的审批人保护其范围内的文件夹，而不是其范围所指定的文件夹。涉及受保护文件夹中屏幕的更改会成为由第二位审批人决定的审核，在每个访问级别都是如此，包括管理。

把播放列表分配给受保护文件夹中屏幕的智能体会得到 pending_review 和审核。在第二位审批人决定之前，屏幕继续播放之前播放的内容。

screenrig screen assign scr_01EXAMPLESCREEN000000000 --playlist-id pl_01WELCOME
screenrig reviews list --kind protected_change
screenrig reviews show rvw_01EXAMPLEREVIEW0000000000

更改会怎样取决于更改本身：

• 审核。 在单个屏幕或一组屏幕上分配播放列表、设置或清除播放列表排程或接管，属于 screen_change 审核。创建、更改或删除受众涉及受保护屏幕的活动，在受保护文件夹内创建文件夹，移动、删除或设置位于受保护文件夹内或包含受保护屏幕的文件夹的默认播放列表，将屏幕或文件夹移入或移出受保护文件夹，以及清除保护，属于 protected_change 审核。更改在批准决定时生效。重命名即时生效。
• 拒绝。 涉及受保护屏幕的标签、字段、位置、时区和墙的编辑，替换屏幕，删除、归档、暂停，显示电源及其排程，播放页面，提示消息，广告库存，触发器目标和排程导入，都会返回 protected_target。要进行更改，审批人通过审核解除保护，完成更改后，再次保护该文件夹。分发的触发器不会改动受保护的屏幕，并对其计数。
• 开放。 恢复、取消归档、重启、重新加载、识别、维护和截图仍可使用。

审核等待提议者以及对提议的智能体或服务客户端负责的人员之外的另一个人。决定者是同一个人时，决定会被拒绝，返回 second_approver_required。项目只有一位审批人时，拒绝信息会提示将另一位成员设为审批人。在文件夹受保护之前提出的更改，在被批准时适用该规则。等待期间已过时的审核返回 review_stale；请重新提议更改。

没有受保护文件夹的项目不为该规则付出任何代价。

预留的活动

标记为预留的活动，只有能够批准审核的人才能更改、暂停、删除或取消预留：所有者，或范围包含该活动整个受众的审批人。人员在控制台的活动表单中开启预留。智能体和服务客户端在任何访问级别都不能更改预留的活动，其尝试会返回 reserved_item。预留承载品牌固定排程的活动，管理者或智能体就不会意外更改它。

标签不是范围

范围是文件夹和单个屏幕。任何可以更改屏幕的人都可以写入其标签，因此标签范围会让一位管理者扩大自己或另一位管理者的触达范围。请用文件夹表示所有权，用标签在其内部进行选择。

按标签选择的设备组操作或活动，会对受限人员整体拒绝，返回 outside_screen_scope，提示信息会说明改为按 ID 或按文件夹选择。

智能体

受限智能体通过 CLI 工作的方式，与受限成员在控制台中的方式相同。

screenrig agent status
screenrig screen list
screenrig screen folder list
screenrig screen pair "$PAIRING_CODE" --folder sfd_01LOBBY --name "Lobby entrance"
screenrig screen assign scr_01EXAMPLESCREEN000000000 --playlist-id pl_01WELCOME
screenrig screen folder update sfd_01LOBBY --unprotect
screenrig campaign show cmp_01EXAMPLECAMPAIGN0000000

• agent status 显示智能体的 screen_scope 以及对其负责的人员的 person_screen_scope。
• screen list 和 screen folder list 仅包含其屏幕和文件夹。
• screen pair 接受 --folder，并需要范围内的文件夹。
• screen folder update ID --unprotect 提议移除文件夹的保护，单独发送。它会成为由第二位审批人决定的审核。
• campaign show 打印 editable 和 reserved。
• 未选择项目时，screen list 会省略智能体受限的项目。请选择该项目。

拒绝及其解决办法

每个拒绝都会在其 hint 中指明重新获得访问的方法。

被接受的受保护更改会返回 202，附带 status: pending_review 和审核，与拥有提议权限的智能体得到的答复相同。之后请接着使用 screenrig reviews show ID。

审计

每项更改都是项目日志中的一个事件，写在产生该更改的同一事务中：

审核会写入常规的 review.* 事件，批准的人员是审核所应用内容的操作者。

API

所有者的路由使用控制台会话。

组织路由使用管理员的仪表板会话。智能体和持有者凭证没有仪表板会话。

API 参考列出每个请求、响应和问题。问题见问题类型。

相关

• 身份验证：访问级别、审核设置和上传者。
• 智能体：智能体的更改如何经过审核。
• 标牌 CLI：屏幕文件夹和设备组命令。
• 服务客户端：服务器和 CI 作业的凭据。