播放列表 API

版本化播放列表列表，可能暴露广告位页面。v1 列表拒绝持有 version_required 的广告文档页面，而非过滤。

页面如 listPlaylists，最新优先，每页最多 200 条，且当页面存储的播放列表达到 8 MiB 时减少。next_cursor 是最后返回行的位置，当还有更多行时；将其作为 after 传回，使用相同过滤器，获取下一页。最后一页时 next_cursor 为 null。library=true 改为列出组织媒体库的播放列表（只读；可对其排期，或基于其模板创建）。

广告位页面联合的创作入口。最多16个广告位页面，至少一个无可见性的普通页面，以及在不同页面上重用一个插槽定义仍由服务器检查。参考解析和DNS仍由服务器检查。

控制台会话（页面编辑器）直接上线创建播放列表，绝不作为提议，并记在该人员名下；需要项目所有者或可批准的成员（否则为 approver_required）。它指定的仍在等待审核的媒体为 media_pending_review (409)，而智能体的直接写入会批准它。

包含 Player 网页应用无法嵌入的 iframe 页面的写入仍会保存；响应包含警告（PlaylistWarning），项目日志会为每个页面记录一个 playlist.iframe_framing_refused 事件。

写入中的 iframe src、fallback_src 或应用 params 读取了显示该播放列表的某个屏幕所缺少的屏幕令牌（{screen.field.NAME} 及原语模式中的其他令牌）时，也会返回 screen_fact_missing 警告，列出前 20 个此类屏幕；这些屏幕的清单会省略该原语。

iframe 的 src 或 fallback_src 若是 Google Slides、Docs 或 Sheets 链接（分享、发布到网络或嵌入），或 Microsoft 365 OneDrive 或 SharePoint 嵌入链接，会重新构建后存储以适配屏幕：Slides 循环并按链接的 delayms 翻页（受页面时长限制），Docs、Sheets、Word 和 Excel 每 5 分钟重新加载。

src 或 fallback_src 中粘贴的 <iframe> 嵌入代码会读取其 src。要求查看者登录的文件会被拒绝，返回 document_not_shared (400)，其 errors[0].field 为该 src 或 fallback_src，detail 指明需要更改的共享设置。

接受广告位页面联合的版本化更新。If-Match 携带播放列表修订版。

控制台会话（页面编辑器）直接上线替换播放列表，绝不作为提议，并记在该人员名下；需要项目所有者或可批准的成员（否则为 approver_required）以及 If-Match（缺少时为 invalid_request）；尚未有人批准的播放列表为 playlist_not_approved (409)，与 patchPlaylistStructure 相同。页面指定的仍在等待审核的媒体为 media_pending_review (409)。

包含 Player 网页应用无法嵌入的 iframe 页面的写入仍会保存；响应包含警告（PlaylistWarning），项目日志会为每个页面记录一个 playlist.iframe_framing_refused 事件。

写入中的 iframe src、fallback_src 或应用 params 读取了显示该播放列表的某个屏幕所缺少的屏幕令牌（{screen.field.NAME} 及原语模式中的其他令牌）时，也会返回 screen_fact_missing 警告，列出前 20 个此类屏幕；这些屏幕的清单会省略该原语。

iframe 的 src 或 fallback_src 若是 Google Slides、Docs 或 Sheets 链接（分享、发布到网络或嵌入），或 Microsoft 365 OneDrive 或 SharePoint 嵌入链接，会重新构建后存储以适配屏幕：Slides 循环并按链接的 delayms 翻页（受页面时长限制），Docs、Sheets、Word 和 Excel 每 5 分钟重新加载。

src 或 fallback_src 中粘贴的 <iframe> 嵌入代码会读取其 src。要求查看者登录的文件会被拒绝，返回 document_not_shared (400)，其 errors[0].field 为该 src 或 fallback_src，detail 指明需要更改的共享设置。

仅更改提供的顶层字段：name、pages、audio、format 或 fields。省略的字段取自同一事务快照。提供的 pages、audio 和 format 会替换完整的值；audio 为 null 会移除配乐，format 为 null 会移除格式。嵌套数组元素不会合并。

仅编辑已批准播放列表的名称不会重新验证或重新解析其未更改的内容，包括较旧的存储页面格式。验证提供的内容和音频/页面提示关系。If-Match 可选保护修订；相同补丁为无操作，幂等重试重放原始响应。

Propose 权限和审核策略与 PUT 相同，包括对所提供 pages 中 Player 网页应用无法嵌入的 iframe 页面的警告。PUT 仍会完整替换文档。

将已认证项目拥有的一个播放列表标记为已删除。只要任何屏幕（包括已归档或待处理的屏幕）仍将其用作默认播放列表、排期内容或接管内容，或者屏幕文件夹仍将其用作默认播放列表，或者活动仍在播放它，就会以 resource_conflict (409) 拒绝。

控制台会话也可删除；它通过 createPlaylistV2 和 updatePlaylistV2 创建和替换播放列表，并通过 patchPlaylistStructure 更改其结构。

已登录人员更改播放列表结构，绝不更改其页面显示内容：名称、页面顺序、保留页面及每个保留页面的提前和可见性。pages 是完整的新顺序；存储的页面若被省略则移除，播放列表不持有的 id 或重复的 id 在 pages[i].id 返回 invalid_request。

已保存页面的画布、转场、audio_cue、图元和备注始终为存储版本：正文中无对应成员，其他成员将被拒绝。

保留的页面经过与任何存储播放列表相同的解析和验证，因此自删除媒体项后会拒绝（resource_conflict），播放列表最多保留一个无可见性的普通页面、16个广告位页面及其 audio_end 提示。advance 替换页面的 advance（广告位页面无此项）；visibility 替换页面的可见性，若为 null 则移除，省略则保持。

如果更改后播放列表保持不变，则视为无操作。If-Match 携带播放列表修订版本且为必需（缺失时返回 invalid_request，过时时返回 revision_conflict）。写入操作会立即在所有显示该播放列表的屏幕上生效，并归因于 playlist.updated 中的人员；它永远不是提议，因此响应永远不会是 202。

尚无人批准的播放列表（approved_revision 0）会被拒绝，返回 playlist_not_approved (409)：请先决定其审核。项目中另一播放列表已使用的名称为 resource_conflict。仅限控制台会话；智能体通过 patchPlaylist 更改播放列表，人通过 updatePlaylistV2 更改页面显示的内容。

响应与任何写入一样携带 warnings（PlaylistWarning），其中包括 screen_fact_missing：显示该播放列表的屏幕缺少其页面的 iframe src 或应用 params 所读取的值时。请求体最大 64 KiB。

The playlist's revisions, newest first: each revision a write stored (a create, a replace, a patch, a structure change, an applied review, a promote) with its name, its page count, the kind of change and who made it.

History begins with the revision a playlist held when revision history was first recorded: until its next write the list holds that revision alone, with change baseline. Revisions are kept for as long as the playlist is. At most 50 per page; next_cursor while more remain, null on the last page.

One revision of the playlist and the playlist as it stood at that revision: its name, pages, soundtrack and format, with revision set to this one. A revision the playlist never had, or one from before its history began, is not_found.

Makes an earlier revision current again by copying it forward: its pages, soundtrack and format become a new revision, the current one plus one, whose change is promoted and restored_from names the revision copied. The playlist keeps its current name, earlier revisions stay as they were, and every screen that shows the playlist updates as for any other write.

If-Match is required and names the current revision (invalid_request when absent, revision_conflict when stale). The pages are resolved again as a structure change resolves them: a selector matches today's media, and media or a web app the revision named that is gone or not ready refuses the promote with the problem a write would get.

内容与当前内容相同的修订不会改变任何东西，并返回当前播放列表。需要可直接发布的凭据（写入需提交审核的凭据不可），或项目所有者、有批准权限的成员的仪表板会话（approver_required）；尚无人批准过的播放列表返回 playlist_not_approved（409）。

与任何写入一样，响应携带 warnings（PlaylistWarning），其中包括 screen_fact_missing：显示该播放列表的屏幕缺少所提升页面的 iframe src 或应用 params 所读取的值时。

设置（用 null 则清除）由模板创建的播放列表的字段值，并根据模板的当前修订版重新生成其页面：值的检查方式与创建时相同，此后对模板所做的品牌变更会同步到此副本。不发送任何值即可仅将副本更新到最新。

审阅类别与其他播放列表写入相同：所有者或可以审批的成员（仪表板会话）以及 Manage 凭据会立即生效，上传者仅限其播放列表和文件夹，Propose 会把更改变成审阅（202）。不是由模板创建的播放列表会返回 invalid_request。If-Match 为可选。

由模板创建的播放列表（按名称排序，最多 1000 个），各自附有其页面所基于的模板修订版，以及模板是否有更新的修订版。

使用这些值由模板创建的播放列表所包含的页面，已按所有播放列表规则检查。仅做计算，不保存任何内容。

向已批准的播放列表添加一个页面，无需发送其他页面：添加到末尾，或添加到 before 所指定页面之前。

播放列表已有的页面按存储原样保留，并与新页面一并一次性重新校验，因此跨页面规则（1 到 100 个页面、一个没有可见性设置的普通页面、16 个广告位页面、1024 个媒体引用）会基于结果判断：违反规则时返回带 field 的 invalid_request（id 已被占用时为 page.id，before 未指向任何页面时为 before）。

播放列表的页面有效期即页面自身的可见性设置（from、until、windows、data），按各屏幕的时区计算，until 为不含端点。

审核类别：在提议级别下，更改会成为一个审核（202）；同一提议者对同一播放列表之后的页面更改，只要仍基于实时修订版本，就会扩展该待处理审核，因此连续的更改不会相互取代，批准要么全部应用，要么都不应用（播放列表已前进时返回 review_stale）；另一位提议者的页面更改所对应的待处理审核既不会被扩展也不会被取代，该更改会以 resource_conflict（409）等待。

使用管理级别，或来自所有者或有批准权成员的控制台会话时（否则为 approver_required），即时生效。If-Match 可选：提供时必须是实时修订版本。尚无人批准的播放列表返回 playlist_not_approved (409)。

上传者（docs/uploaders.md）只能将其文件夹中的媒体页面添加到其某个播放列表（否则返回 outside_upload_scope）；处于提议级别的上传者成员是审核的提议者（kind person）。

就地替换已批准播放列表的一个页面，无需发送其他页面。请求体即该页面，其 id 为 page_id。未知页面返回 not_found。

其余与 addPlaylistPage 相同：与保留的页面一并一次性校验；审核类别（提议时为 202，并链接到待处理的页面变更审核）；使用管理级别或由有批准权的人员操作时即时生效；If-Match 可选；对尚无人批准的播放列表返回 playlist_not_approved。

上传者只能将其文件夹中的某个媒体页面替换为其文件夹中的另一个媒体页面；在提议级别下，也可以替换其自身审核中等待的页面。

移除已批准播放列表的一个页面。播放列表须保留 1 到 100 个页面，以及一个没有可见性设置的普通页面（否则返回 invalid_request）。未知页面返回 not_found。其余与 replacePlaylistPage 相同。上传者只能移除其文件夹中的媒体页面。