onelake-catalog-govern-cli

遥测 — 强制要求。 每次 api.fabric.microsoft.com 调用都必须携带 x-ms-fabric-skill: onelake-catalog-govern-cli（az rest：--headers "x-ms-fabric-skill=onelake-catalog-govern-cli"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项——仍须添加。

重要说明

1. 若要通过工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 若要通过工作区 ID、项类型和项名称查找项的详细信息（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选

OneLake Catalog Govern — CLI（模式分发器）

一项技能覆盖整个 OneLake Catalog Govern 系列。治理角色详情位于四个按需加载的模式参考文档中。此顶层文件仅用于完成以下三项操作：

1. 选择模式（见下表）。
2. 明确安全边界和不可逆写入门槛，避免这些要求在冗长的参考文档中被弱化（见不可逆操作）。
3. 仅加载一个模式参考文档并遵循其中的说明。

必须做 / 优先做 / 避免做

必须做

• 进行任何修正之前，先根据调用者的权限层级查看对应的审计单元。
• 每次执行破坏性、不可逆或大范围写入之前，先应用步骤 2 中针对具体操作的确认门槛。
• 使用所选流程文档中指定的 Fabric Admin、Core、Power BI 或 Graph API 接口；不得将 401 或 403 视为绕过 RBAC 的许可。
• 报告每项治理统计时，都要说明范围、排除项、分页完整性和数据时效性注意事项。

优先做

• 对于数据所有者操作，优先使用权限最小化的 Core 或 Power BI API，而不是要求租户管理员权限。
• 将发现报告为证据、后果、建议操作、优先级和工作量，而不是直接返回清单。
• 先处理所有权和访问范围问题，再进行批量分配或标记。

避免做

• 不得在审计模式下修改租户。
• 不得臆造用于认证、DLP 策略、管理员删除项或第三方项标识分配的写入 API。
• 不得将异步 202 响应报告为成功完成。

步骤 1 — 选择模式

两个维度 → 2×2 网格。 权限层级（可访问的 API 接口）× 操作（审计或修正）。每个单元涵盖全部三个 Govern 支柱（健康 / 保护 / 信任）。

	审计（只读）	修正（写入）
Fabric Admin — /v1/admin/*，仅限 Fabric 租户管理员	admin-audit	admin-remediate
数据所有者 / 运营管理员 — Core API + 工作区/域/容量管理员，无租户管理员权限	dataowner-audit	dataowner-remediate

模式	加载此参考文档	角色 / 权限层级	范围	读取	写入
admin-audit	references/admin-audit.md	Fabric 租户管理员（/v1/admin/*）	整个租户	✅	❌
admin-remediate	references/admin-remediate.md	仅限 Fabric 租户管理员 — 每项 /v1/admin/* 写入都要求具备 Fabric 管理员角色；域和容量管理员不符合要求	整个租户	✅	✅
dataowner-audit	references/dataowner-audit.md	非管理员工作区或域所有者（仅 Core API）	调用者管理的工作区（按请求扩大到可访问的工作区）	✅	❌
dataowner-remediate	references/dataowner-remediate.md	同时也是域 / 工作区 / 容量管理员的数据所有者 — Core 和 Power BI API 写入，无租户管理员权限	调用者拥有相应角色的对象	✅	✅（自助服务）

路由规则

• 从审计模式开始。 在确认当前状态之前，绝不执行修复。审计后在同一层级内修复，除非调用方的权限发生变化。
• 根据调用方可访问的 API 表面选择层级，而不是根据职位名称：需要访问 /v1/admin/* 的 Fabric 租户管理员 → admin-* 单元；通过工作区／域／容量角色操作的数据所有者 → dataowner-* 单元。
• “修复／分配／应用／创建／删除” → 修复单元。租户级写入（创建／删除域、批量分配域、域角色、批量标签、认证）→ admin-remediate。单个工作区的 assignToDomain 或 assignToCapacity、应用标签、设置说明、刷新和项目身份 → dataowner-remediate（这些操作需要对象范围的角色，而非租户管理员权限）。
• 读写分离是安全边界：即使提示词要求修改，审计模式也不得修改租户。如果你处于审计模式，而用户要求执行写入操作，请明确切换到对应的修复模式——不要自行变通执行写入。

层级 = API 表面，而非角色名称。 admin-* 模式调用 /v1/admin/*，并要求具备 Fabric 租户管理员角色（Fabric 管理员／Power Platform 管理员／M365 全局管理员）——域、容量和工作区管理员不符合要求，即使是其自己的域也不例外。dataowner-* 模式使用 Core/Power BI API，其范围由调用方在特定对象上已有的角色限定。因此，不具备 Fabric 租户管理员身份的域／WS／容量管理员应始终使用 dataowner-* 单元；只有在另行授予 Fabric 租户管理员角色后，才应切换到 admin-*。角色是模式内部的范围分支；只有不同的 API 表面才有理由使用单独的模式。

⚠️ 已知的 Fabric 缺口——范围限定的治理没有非管理员 API。 目前，不具备 Fabric 租户管理员身份的域管理员或工作区管理员无法通过 API 查看其范围限定的治理状态：/v1/admin/* 会拒绝其请求（该接口要求 Fabric 租户管理员角色——参见 分配域工作区中的权限说明），而 Core API 没有可列出域内工作区或返回域治理状态的端点。dataowner-audit 只能报告调用方可直接访问的工作区——无法查看“我的整个域”。如果域／WS 管理员询问其范围内的治理详情，请一开始就说明此限制，不要将其导向会返回 401/403 的 admin-* 模式。

第 2 步 — 不可逆操作 — 必须执行的检查关卡（执行任何写入前阅读）

⚠️ 为何将此内容放在这里，而不只放在模式参考中。 这些操作会终止流程， 且难以撤销。如果此类指令只是大型参考文件中数十条内容中的一条，读者可能 看到了却不经意间跳过。因此，这里在自动加载的调度器正文中再次列出，以便检查关卡 在写入之前触发，而非之后。完整流程仍保留在 remediate 模式参考中（admin-remediate.md、dataowner-remediate.md）；这里是检查清单，而非替代方案。

在任一 remediate 模式中执行以下任何操作前，必须通过检查关卡。模式列显示由哪个角色负责该操作：

不可逆／终止操作	模式	必须首先触发的检查关卡
删除域（DELETE /v1/admin/domains/{id}）	admin	检查子域（parentDomainId）以及该域和每个子域的工作区分配数量。如果任何工作区会因此成为孤立工作区，停止并获取用户明确确认，确认内容必须列出受影响的域／工作区。REST API 不会阻止级联删除——检查是你的责任。请参阅 domain-crud.md § 删除域。
删除标记定义	admin	先报告有多少项内容使用了该标记——删除会使其从所有位置解除关联，且无法撤销。
将工作区批量分配给某个域	admin	检查每个目标当前的 domainId，并在静默覆盖现有分配之前发出警告。先对目标列表进行试运行。
将主体从域角色中移除	admin	确认此操作不会导致域失去所有者；指出要移除的主体。
批量更改敏感度标签	admin	试运行：显示确切的受影响项列表及更改前后的标签，并获取确认。不支持服务主体／托管标识——调用会失败。
写入租户设置（例如启用认证）	admin	读取并显示当前值，然后显示拟议值——此操作会影响整个租户。
将某个工作区分配给域／从域取消分配	dataowner	移动即为重新分配——确认当前的 domainId，并指出该工作区将离开的域。需要域贡献者和工作区管理员权限；失败时说明缺少哪项权限。
重新分配项所有权（项身份、预览）	dataowner	只会分配给调用者；需要对该项及其子项拥有写入权限。确认预期身份。
将工作区分配给容量	dataowner	需要工作区管理员权限，以及容量贡献者／管理员权限。操作异步返回 202——不要仅凭 202 报告成功；应轮询直到达到终态。

不要承诺通过没有写入 API 的方式进行修复。 租户管理员无法通过写入路由处理认证、DLP 策略和项的删除。对于这些情况，应整理一份可采取行动的联系人名单——请参阅 references/admin-remediate/no-write-api-escalation.md § 将发现的问题转交给能够修复的人。

第 3 步 — 加载参考并继续

只加载与第 1 步匹配的那一份模式参考，并从头到尾遵循其中的说明。此处为共享 背景和每个末端流程编制了索引，因此调度器中的每个文件都只需一次跳转即可到达。 参考文件是叶节点：加载后，如需其他流程，请返回此索引。

共享治理参考资料

• 治理支柱 — 三大支柱、“良好”的标准以及报告规范
• 治理数据源 — 已验证的 API 字段覆盖情况、产品盲点以及报告规范
• 治理角色 — 权限级别、域/工作区角色以及见解刷新延迟
• 目录概念 — 实体模型以及由 API 支持的术语与概念性术语
• ../../common/COMMON-CORE.md — 仓库级 Fabric REST 模式、身份验证和分页
• ../../common/COMMON-CLI.md — 仓库级 CLI 实现（az rest、分页、身份验证方案）

模式分发器

• 管理员审计 — 租户范围的只读治理评估
• 管理员审计范围 — 可治理范围分母、排除项和已知盲点
• 管理员审计评估 — 端到端评估工作流、优先级排序和交付物约定
• 管理员修复 — 通过 Admin API 在租户范围内执行受保护的写入操作
• 数据所有者审计 — 通过 Core API 执行调用者范围的只读检查
• 数据所有者修复 — 通过 Core 和 Power BI API 执行最小权限写入操作

管理员审计流程

• 域健康状况 — 分配、所有权、参与者范围和元数据
• 工作区健康状况 — 空工作区/非活动工作区和管理员单点风险
• 容量健康状况 — 容量状态、所有权和域对齐情况
• 项目清单 — Admin 与扫描器的清单及字段覆盖情况
• 项目健康状况 — 所有权、陈旧情况和刷新状态
• 保护覆盖情况 — 敏感度标签和 DLP 可见性
• 信任管理 — 说明、认可和标签覆盖情况

管理员修复流程

• 域生命周期 — 创建、更新和安全删除域
• 工作区分配 — 选择批量分配方法并执行试运行
• 域角色 — 分配管理员和参与者
• 标签 — 管理租户标签定义
• 项目敏感度标签 — 受保护的批量标签更改
• 域默认标签 — 防止新增未标记积压项
• 信任修复 — 启用认证和委派操作
• 无写入操作升级处理 — 识别缺失的 API 和能够采取行动的指定负责人

数据所有者流程

• 数据所有者工作区健康状况 — 在调用者范围内检查空工作区和非活动工作区

示例

Audit our tenant's OneLake catalog governance posture and prioritize the findings.

Which workspaces I administer are not assigned to a domain?

Show a dry run for assigning these workspaces to the Finance domain, including current assignments.

Find unlabeled items tenant-wide and explain which remediations require a tenant admin versus a data owner.