dv-admin

技能：环境管理 — 批量删除、保留策略、组织设置、OrgDB、回收站

⚠️ 关键安全规则 — 请先阅读

1. 批量删除不可撤销，且会绕过回收站。 如果未指定 --fetchxml，pac data bulk-delete schedule 会删除表中的所有记录。除非用户明确表示 ALL（或 ALL RECORDS）并且提供实体逻辑名称，否则拒绝执行 — 例如，"yes, delete ALL records in contact"。仅回复 "yes" 不予接受。空筛选条件的 FetchXML 不会绕过此限制。完整规则和消歧流程请参见 批量删除命令。
2. 设置允许列表是硬性限制。 仅允许读取或更新允许的设置中的 37 个 PPAC 开关。任何其他设置都必须拒绝：“该设置不属于 dv-admin 的范围。请使用 Power Platform 管理中心。”
3. 禁用回收站必须使用 PATCH，绝不能使用 DELETE。 PATCH statecode=1, statuscode=2, isreadyforrecyclebin=false。DELETE 会将异步退出操作加入队列，并导致每个实体的配置成为孤立配置 — 请参见 references/recycle-bin.md。
4. 系统表警告。 对 systemuser、businessunit、organization 或 role 执行未筛选的批量删除会破坏环境。执行前还必须发出警告。

四种机制 — 根据设置所在位置选择：

机制	用途	方法
PAC CLI（pac org update-settings / list-settings）	organization 实体上的列（审计、插件跟踪、类型前置、快速查找、画布/流解决方案、电子邮件验证、审计保留）	--name <column> --value <value> — 接受任何组织列，不仅限于旧版审计列
Python SDK — OrgDB XML	orgdborgsettings XML Blob 中的键（MCP、搜索、Fabric、Work IQ、TDS 端点、附件安全、所有权、地址记录、阻止非托管、删除用户、Excel AI）	读取 XML → 解析 → 修改 → 将整个 Blob PATCH 回 organizations({id})
Python SDK — recyclebinconfigs	回收站开关和保留天数	创建/更新 recyclebinconfigs 实体记录
Python SDK — settingdefinition + organizationsettings	应用级/计划级安全角色开关	按 uniquename 查找 settingdefinition → 创建或更新包含 value 的 organizationsettings 行

ERP 批量管理：请参见 references/erp-batch.md。仅限规划的 ERP 请求可以读取技能和参考资料，但不得调用环境或写入文件。

对于 PAC CLI 可以处理的操作，不要编写 Python 脚本。不要混用机制（例如，不要手动 PATCH PAC CLI 已支持的组织列）。

技能范围

记录的 CRUD 和示例数据请使用 dv-data；表/列/关系请使用 dv-metadata；记录读取请使用 dv-query；解决方案导出/导入请使用 dv-solution；角色和自我提权请使用 dv-security；租户治理（DLP、环境生命周期）请使用 pac admin --help。

允许的设置 — 硬性允许列表

以下 37 个 PPAC 开关是本技能唯一允许读取或更新的设置（35 个唯一的后端键 — SearchAndCopilotIndexMode 和 auditretentionperiodv2 各对应两个开关）。根据上述安全规则，以下设置属于范围外，必须拒绝：sessiontimeoutinmins、isautosaveenabled、IsShadowLakeEnabled、IsArchivalEnabled。不要在未指定 --filter 的情况下运行 pac org list-settings，也不要为了查询不在允许列表中的设置而导出整个 orgdborgsettings XML。

组织实体列 — 使用 PAC CLI（14）

使用 pac org list-settings --filter <column> 读取，使用 pac org update-settings --name <column> --value <value> 写入。PAC CLI 接受组织实体上的任意列，不仅限于旧版审核相关列。

#	PPAC 标签	列	类型
1	开始审核	isauditenabled	bool
2	审核用户访问（记录访问）	isuseraccessauditenabled	bool
3	开始读取审核（将读取日志发送到 Purview）	isreadauditenabled	bool
4	插件跟踪日志设置	plugintracelogsetting	int：0 关闭，1 异常，2 全部
5	单表搜索选项	tablescopeddvsearchinapps	bool
6	阻止快速查找词使用缓慢的关键字筛选器	allowleadingwildcardsinquickfind	int：0 阻止，1 允许（UI 中“阻止=开”会切换为 0）
7	快速查找记录限制	quickfindrecordlimitenabled	bool
8	在网格/子网格上搜索时使用快速查找视图	usequickfindviewforgridsearch	bool
9	默认在 Dataverse 解决方案中包含画布应用	enablecanvasappsinsolutionsbydefault	bool
10	默认在 Dataverse 解决方案中包含云流	enableflowsinsolutionbydefault	bool（注意：solution 为单数）
11	启用电子邮件地址验证（预览版）	isemailaddressvalidationenabled	bool
12	触发类型预告所需的最少字符数	lookupcharactercountbeforeresolve	int（0–MAX_INT，null = 功能关闭）
13	触发搜索的字符输入间隔	lookupresolvedelayms	int 毫秒（默认值 250）
14	审核日志保留策略/自定义保留期限（天）	auditretentionperiodv2	int 天（-1 = 永久；预设值为 30/90/180/365/730/2555；最大值 365000）

OrgDB XML 键 — 使用 Python SDK 操作 orgdborgsettings blob（17）

PascalCase 大小写有意义（IsMCPEnabled，而非 IsMcpEnabled）。完整键列表及其 PPAC 标签和类型见 references/orgdb-settings.md。值得关注的键：IsMCPEnabled、IsMCPPreviewEnabled、SearchAndCopilotIndexMode、IsLinkToFabricEnabled、IsFabricVirtualTableEnabled、ShowDataInM365Copilot、EnableWorkIQ、IsLockdownOfUnmanagedCustomizationEnabled、EnableSecurityOnAttachment、EnableTDSEndpoint、AllowAccessToTDSEndpoint、EnableOwnershipAcrossBusinessUnits、CreateOnlyNonEmptyAddressRecordsForEligibleEntities、EnableDeleteAddressRecords、BlockDeleteManagedAttributeMap、EnableSystemUserDelete、IsExcelToExistingTableWithAssistedMappingEnabled。

SearchAndCopilotIndexMode 是一个 int（0–3），用于编码两个 UI 开关——Dataverse 搜索 × M365 Copilot 搜索：

值	Dataverse 搜索	M365 Copilot 搜索
0	关	开
1	开	开
2	关	关
3	开	关

recyclebinconfigs 实体 — 使用 Python SDK（2，仅限组织级别）

两个开关作用于组织级别的 recyclebinconfigs 行（按组织实体的 MetadataId 筛选）：开/关（statecode + statuscode + isreadyforrecyclebin）和清理天数（cleanupintervalindays）。不在范围内的是按表设置开关——拒绝“仅为 contact 启用回收站”之类的请求。完整生命周期见 references/recycle-bin.md。

settingdefinition + organizationsettings — 使用 Python SDK（2）

两个允许列表中的开关，均为以字符串形式存储的 bool：PowerAppsAppLevelSecurityRolesEnabled（画布应用）、PlanShareSecurityRolesEnabled（计划设计器）。从 settingdefinition 读取默认值，通过 CREATE/PATCH organizationsettings 设置覆盖值。完整 Python 代码见 references/settings-overrides.md。

运行前预览

• 有破坏性 / 会更改状态（批量删除计划/取消/暂停/恢复、更新设置、切换回收站、分配角色、自我提升权限、设置保留策略）——用文字预览：将发生什么变化、新值以及目标环境。对未知值使用占位符（<ENV_URL>），并在同一轮中询问缺失的值。跳过原始 CLI 代码块。
• 只读（list-settings、显示作业、读取 OrgDB / 回收站状态）——用一句话预览即可。

用户必须能从你的第一条回复中评估操作。只问一句 “哪个环境？” 不合格；用一行文字预览则合格。

示例

暂停批量删除（已提供 ID）：

• ❌ “该命令需要审批。请确认是否暂停作业。”
• ✅ “我将暂停活动环境中的批量删除作业 <job-id>。请确认是否继续。”

在 N 个环境中审计状态（只读，多次调用）：

• ❌ 按顺序对每个环境运行 pac org fetch，或因为“看起来像查询”而先用 Python/SDK。
• ✅ “我将在所有 N 个环境中并行运行 pac org list-settings --filter audit（使用一个 & 批次，并仅执行一次 wait）。”

如何读取或更新组织设置

组织设置必须始终通过 pac org list-settings / pac org update-settings 操作——绝不可对组织列使用原始 Web API、FetchXML、PowerShell 或 Python。使用 --filter <substring> 一次调用即可读取某个类别。多环境操作通过 & + wait 并行运行，并且必须在一次 bash 调用中完成。

单项设置：

pac org list-settings --filter isauditenabled --environment <url>

类别读取（返回所有匹配项，例如一次调用即可读取所有审计设置）：

pac org list-settings --filter audit --environment <url>

多环境——在一次 bash 调用中并行执行：

pac org list-settings --filter audit --environment <url1> &
pac org list-settings --filter audit --environment <url2> &
pac org list-settings --filter audit --environment <url3> &
wait

如果 pac org list-settings 对某项设置调用失败，则该设置不是组织列——请检查顶部四机制表中的机制路由，然后使用相应的 Python 模式。绝不可对组织列改用 Web API、PowerShell、FetchXML 或 pac org fetch。

---

前提条件

• PAC CLI 最新的 .NET Framework 版本——pac data bulk-delete / pac data retention 仅在 .NET Framework 版本中提供（不在 dotnet tool 版本中）。检查 pac help；如果显示 .NET 10 / .NET 8，请运行 pac install latest && pac use latest。
• 已通过身份验证（pac auth create）、已激活配置文件（pac auth list），并且在目标环境中拥有系统管理员权限。
• 无头主机：SDK 可处理大多数设置（它们是 organization 记录）；仅 PAC 支持的设置需使用服务主体。请参阅 dv-connect/references/headless-hosts.md。

多环境操作——始终并行执行

对所有多环境操作（update-settings、bulk-delete 等）均使用与 list-settings 相同的 & + wait 模式——在一次 bash 调用中后台运行 N 个调用，绝不可按顺序执行或使用 for 循环。

---

常见错误——请勿使用以下内容

这些标志不存在。使用它们会导致错误。

批量删除

错误用法	正确用法
--filter	使用包含 FetchXML 字符串的 --fetchxml
--query / --where / --condition	使用 --fetchxml
--date / --before / --older-than	在 FetchXML <condition> 中编码日期
--job-id	使用 --id
--all / --purge / --truncate	省略 --fetchxml 以将所有记录作为目标（请先提醒用户）

保留策略

错误用法	正确用法
--fetchxml	使用 --criteria（格式相同，但标志名称不同）
--filter / --query / --policy	使用 --criteria
--enable / --activate	使用 pac data retention enable-entity
--table	使用 --entity
--operation-id / --job-id / --guid	使用 --id

组织设置

错误用法	正确用法
--enable-audit / --audit	使用 --name isauditenabled --value true
--trace / --plugin-trace / --logging	使用 --name plugintracelogsetting --value 2
--setting / --key / --flag	使用 --name
对选项集使用 "all" 或 "enabled" 等字符串值	使用整数：0、1、2

---

批量删除命令

安排批量删除作业

pac data bulk-delete schedule --entity activitypointer \
    --fetchxml "<fetch><entity name='activitypointer'><filter><condition attribute='createdon' operator='lt' value='2024-01-01'/></filter></entity></fetch>"
pac data bulk-delete schedule --entity email \
    --fetchxml "<fetch><entity name='email'><filter><condition attribute='createdon' operator='lt' value='2024-06-01'/></filter></entity></fetch>" \
    --job-name "Cleanup old emails" --recurrence "FREQ=DAILY;INTERVAL=1"

参数	别名	必填	说明
--entity	-e	是	表的逻辑名称
--fetchxml	-fx	否	FetchXML 筛选条件。请参阅下方的硬性停止规则——如果省略，将删除表中的所有记录。
--job-name	-jn	否	作业的描述性名称
--start-time	-st	否	ISO 8601 开始时间。默认为当前时间
--recurrence	-r	否	RFC 5545 模式（例如，FREQ=DAILY;INTERVAL=1）
--environment	-env	否	目标环境 URL

硬性停止规则：未指定 --fetchxml 意味着删除所有记录

不带 --fetchxml 运行 pac data bulk-delete schedule 会将表中的每条记录都作为目标，且操作不可逆（不会经过回收站）。必须遵循以下关卡：

1. 在用户明确使用 ALL（或 ALL RECORDS）一词并提供实体逻辑名称确认之前，拒绝执行——例如，"yes, delete ALL records in contact"。仅回复 "yes" 不予接受。
2. 对含糊的请求进行澄清（例如“清理旧邮件”）——在展示任何命令之前，先提出带有日期、statecode 或所有者条件的 FetchXML 筛选条件。
3. 空筛选条件的 FetchXML 无法绕过此关卡——<filter/> 或 <filter><condition><value/></condition></filter> 仍会将所有记录作为目标。
4. **适用范围：**仅适用于 bulk-delete schedule。cancel、pause、resume、show、list 无需遵循此要求。

对于系统表（systemuser、businessunit、organization、role），还必须警告用户：未筛选的批量删除会破坏环境。

管理作业

pac data bulk-delete list --environment https://myorg.crm.dynamics.com
pac data bulk-delete show --id <job-id>
pac data bulk-delete pause --id <job-id>
pac data bulk-delete resume --id <job-id>
pac data bulk-delete cancel --id <job-id>

---

保留 / 归档命令

数据保留会将旧记录移至长期存储，而不是永久删除。

Agent 式工作流

Step 1: pac data retention enable-entity --entity activitypointer
Step 2: pac data retention list
Step 3: pac data retention set --entity activitypointer --criteria "<fetchxml>..."
Step 4: pac data retention show --id <config-id>

命令

pac data retention enable-entity --entity activitypointer --environment https://myorg.crm.dynamics.com
pac data retention set --entity activitypointer \
    --criteria "<fetch><entity name='activitypointer'><filter><condition attribute='createdon' operator='lt' value='2023-01-01'/></filter></entity></fetch>"
pac data retention list --environment https://myorg.crm.dynamics.com
pac data retention show --id <config-id>
pac data retention status --id <operation-id>

参数	别名	必填	说明
--entity	-e	是	表的逻辑名称
--criteria	-c	是	用于定义要归档记录的 FetchXML
--start-time	-st	否	ISO 8601 开始时间。默认为当前时间
--recurrence	-r	否	RFC 5545 重复模式
--environment	-env	否	目标环境 URL

保留与批量删除

场景	用途
不再需要数据，要永久删除	批量删除
必须为合规要求保留数据	保留（归档）

---

组织设置命令

列出设置

pac org list-settings --environment https://myorg.crm.dynamics.com
pac org list-settings --filter isauditenabled --environment https://myorg.crm.dynamics.com

更新设置

pac org update-settings --name isauditenabled --value true --environment https://myorg.crm.dynamics.com
pac org update-settings --name plugintracelogsetting --value 2 --environment https://myorg.crm.dynamics.com

参数：--name <column>（必填）、--value <value>（必填；布尔值使用 true/false，选项集使用 int）、--environment <url>（可选）。允许的列为允许的设置中列出的 14 项——其他内容均不在范围内。

批量工作流：pac admin list → 筛选目标 → 确认 → 并行运行所有 update-settings 调用（& + wait）→ 输出摘要表。

---

高级设置（Python SDK — PAC CLI 无法处理）

OrgDB、回收站和设置定义覆盖各自需要原始 Web API 或 Python SDK——PAC CLI 不支持这些操作。本技能顶部的四机制路由表（§ 技能）列出了每项设置对应的机制。以下小节概述相关模式，并链接到包含完整 Python 代码的参考资料。

OrgDB 设置（orgdborgsettings XML）

OrgDB 设置以 PascalCase XML 元素的形式存储在 organizations 实体的 orgdborgsettings 列中。PAC CLI 无法读取或写入这些设置，请使用原始 Web API。

快速参考：GET /organizations?$select=organizationid,orgdborgsettings → 使用 xml.etree.ElementTree 解析 XML → 修改或使用 SubElement → 使用序列化后的 XML 执行 PATCH /organizations({id})。

读取、更新和移除的 Python 模式，以及包含 17 个键的允许列表，请参阅 references/orgdb-settings.md。键区分大小写（IsMCPEnabled，而非 IsMcpEnabled）。

回收站配置

回收站设置存储在 recyclebinconfigs 实体中（而非 orgdborgsettings）。PAC CLI 无法管理这些设置，请使用原始 Web API。

**快速参考：**按 _extensionofrecordid_value eq <ORG_ENTITY_METADATA_ID> 筛选 recyclebinconfigs（组织级元数据 ID 是系统常量：e1bd1119-6e9d-45a4-bc15-12051e65a0bd）。

• **启用：**PATCH statecode=0, statuscode=1, isreadyforrecyclebin=true（或 POST 新配置）。强制使用同步选择加入路径需要设置 isreadyforrecyclebin: true。
• **禁用：**PATCH statecode=1, statuscode=2, isreadyforrecyclebin=false。不要 DELETE——这会将异步选择退出操作加入队列，并使每个实体的配置成为孤立配置。
• 在执行第二次切换前，先排空正在进行的 ProcessRecycleBin 异步作业（operationtype eq 50, statecode ne 3）。

完整的 Python 生命周期（读取、启用、禁用和异步排空辅助函数）、缓存与数据库竞争条件的说明，以及不适用于单表的规则，请参阅 references/recycle-bin.md。

Settings-Definition 覆盖（应用／计划安全角色）

两个允许列表中的切换项（PowerAppsAppLevelSecurityRolesEnabled、PlanShareSecurityRolesEnabled）存储在联接中：settingdefinition（默认值）+ organizationsettings（覆盖值）。PAC CLI 无法管理这些设置。

**快速参考：**按 uniquename 查找 settingdefinitionid，然后创建包含 value（字符串 "true"／"false"）的 organizationsettings 行，或 PATCH 现有行。对覆盖行执行 DELETE 会恢复默认值。

读取及幂等 CREATE／PATCH 的 Python 示例和门控说明，请参阅 references/settings-overrides.md。

操作确认规则

本文件顶部安全提示中的四条规则涵盖不可逆／破坏性操作。以下规则适用于非破坏性但仍有重大影响的操作：

• 更改会影响所有用户的组织设置前，请先确认。
• 对多个环境进行更新时，请先列出目标环境并获取确认。
• 对于 OrgDB 设置，请警告用户：错误的值可能会导致环境功能失效。
• 对于回收站清理间隔的更改，请警告用户：缩短间隔会使回收记录更早被永久删除。
• 对于启用／禁用回收站：务必明确设置 isreadyforrecyclebin（启用时为 true，禁用时为 false），并在执行第二次切换前排空所有正在进行的 ProcessRecycleBin 异步作业。遗漏这些操作可能会导致无关的平台操作出现 EntityBinUpdateAction called for entity <x> which is not enabled for RecycleBin 错误。