managing-managed-event-subscription

管理 ManagedEventSubscription

创建、读取、更新和删除 ManagedEventSubscription 元数据 — 这是 Salesforce 中用于持久订阅平台事件频道并跟踪托管重放的构造。

范围

• 范围内：为创建、读取、更新和删除操作生成并修改 .managedEventSubscription-meta.xml 文件
• 范围外：创建底层平台事件（__e）频道本身；基于 Flow 或 Apex 的事件订阅；将元数据部署到组织
• 只生成一个文件 — .managedEventSubscription-meta.xml 文件。切勿生成引用的平台事件对象或任何其他元数据类型。

---

澄清问题

生成前，如果信息尚不明确，请确认：

• 主题名称是什么？（参见 references/topic-name-formats.md 中的格式表）
• 开发者名称是什么？（创建时必填 — 只能包含字母数字字符和下划线，不得有空格；如果已知 Id，读取／更新／删除时可选）
• 标签是什么（便于人类识别的名称）？
• 默认重放预设是什么 — LATEST（默认）还是 EARLIEST？
• 错误恢复重放预设是什么 — LATEST（默认）还是 EARLIEST？
• 初始状态应是什么 — RUN（活动）还是 STOP（非活动）？（默认：RUN）

---

必需输入

继续前，收集或推断以下信息：

• 操作：创建、读取、更新或删除
• DeveloperName：创建时必填（将成为文件名）；如果改为提供 Id，读取／更新／删除时可选
• Id：Tooling API 记录 Id；读取／更新／删除时，可用于代替 DeveloperName 标识订阅
• label：便于人类识别的标签（可包含空格）
• topicName：事件频道路径 — 请阅读 references/topic-name-formats.md 了解有效格式（平台事件、变更事件、自定义频道）
• defaultReplay：LATEST 或 EARLIEST（默认：LATEST）
• errorRecoveryReplay：LATEST 或 EARLIEST（默认：LATEST）
• state：RUN 或 STOP（默认：RUN）— PAUSE 保留供平台内部使用，使用时会被拒绝并返回 INVALID_INPUT
• version：Metadata API 版本（默认：与组织 API 版本一致，例如 67.0）

---

工作流

创建

1. 收集输入 — 确认 DeveloperName、label、topicName、defaultReplay、errorRecoveryReplay、state 和 version。对省略的字段应用默认值。如果未提供 DeveloperName，请询问用户；不要根据 label 推导。
2. 确认主题存在 — 继续前，请用户确认组织中已存在该事件频道。切勿自行生成平台事件对象 — 这超出了此技能的范围。如果用户表示频道尚不存在，请停止并引导他们先使用 generating-platform-event 技能创建，然后再回到这里。
3. 读取模板 — 加载 assets/managed-event-subscription-template.xml，作为起始结构。
4. 生成文件 — 生成 managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml，并填入用户提供的值。
5. 验证 — 在展示输出前，运行下方的检查清单。
6. 指导用户订阅 — 部署后，可在调用 Pub/Sub API ManagedSubscribe RPC 时使用 DeveloperName 或记录 Id 来标识订阅。若要获取 Id，请通过 Tooling API 运行：SELECT Id, DeveloperName FROM ManagedEventSubscription WHERE DeveloperName='<DeveloperName>'

读取

1. 标识订阅 — 接受 Id 或 DeveloperName；如果提供了 Id，优先使用它。
2. 显示文件路径 — managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml（如果已知 DeveloperName）。
3. 检索并显示 — 读取并展示当前 XML 内容。

更新

1. 识别订阅 — 接受 Id 或 DeveloperName；如果提供了 Id，优先使用。
2. 读取现有文件 — 修改前先加载当前内容。
3. 应用更改 — 仅更新指定字段；保留所有其他字段。
4. 阅读 references/update-constraints.md，了解创建后无法更改的字段。
5. 验证 — 在呈现输出前运行以下检查清单。

删除

1. 识别订阅 — 接受 Id 或 DeveloperName；继续操作前请用户确认。
2. 警告 — 删除 ManagedEventSubscription 会永久移除重放跟踪状态。
3. 提供删除说明 — 说明如何移除文件，以及如何使用 destructiveChanges.xml 部署破坏性更改。
4. 阅读 references/delete-guide.md，了解破坏性部署流程。

---

规则 / 约束

约束	原因
<topicName> 必须使用有效的路径前缀	平台事件使用 /event/Name__e；更改事件使用 /data/Name；所有格式请参阅 references/topic-name-formats.md
<defaultReplay> 和 <errorRecoveryReplay> 必须为 LATEST 或 EARLIEST	这是仅有的有效枚举值；其他任何值都会导致元数据验证失败
<state> 必须为 RUN 或 STOP	PAUSE 保留供平台内部使用 — API 会拒绝该值，并返回 INVALID_INPUT: You can create a managed event subscription state field only to RUN or STOP
必须包含全部六个必需元素	topicName、defaultReplay、errorRecoveryReplay、label、state、version 均为必需项；省略任何一项都会导致部署错误
DeveloperName 在组织内必须唯一	名称重复会导致 DUPLICATE_DEVELOPER_NAME 错误
不要包含 <namespacePrefix>、<id> 或 <createdDate>	这些是只读的平台字段；包含它们会导致未打包组织中的部署失败

---

注意事项

问题	解决方法
部署时出现 The topicName field is invalid	格式错误，或该事件在组织中不存在 — 阅读 references/topic-name-formats.md 了解正确路径
删除后重新创建会丢失重放状态	删除会丢弃已存储的重放位置；重新创建时会从 defaultReplay 开始 — 删除后避免重复使用相同的 DeveloperName
SOQL 查询出现 INVALID_TYPE	ManagedEventSubscription 只能通过 Tooling API 查询，不能通过标准 SOQL 查询
高吞吐量频道上的 EARLIEST 重放	激活时可能触发长达 72 小时的积压重放；务必向用户确认
较旧组织不支持此元数据	ManagedEventSubscription 要求 API v60.0+；请检查组织的 API 版本
生成的 XML 中出现 eventChannel 或 isActive	这些字段名不正确 — 请改用 topicName 和 state（RUN/STOP）
生成的 XML 中出现 PAUSE 状态	PAUSE 保留供平台内部使用，会因 INVALID_INPUT 被拒绝 — 只能使用 RUN 或 STOP
用户不确定如何识别 Pub/Sub API 的订阅	DeveloperName 和记录 Id 均可用于 ManagedSubscribe RPC — 如有需要，可通过 Tooling API 获取 Id：SELECT Id FROM ManagedEventSubscription WHERE DeveloperName='<name>'
更改未立即反映在 Pub/Sub API 中	创建、更新或删除后，Pub/Sub API 最多可能需要约 2 分钟才能反映新配置；如果 ManagedSubscribe 返回 NOT_FOUND，请等待后重试

---

验证清单

在展示生成的任何 XML 之前：

• <topicName> 是否符合 references/topic-name-formats.md 中的有效路径格式？（/event/Name__e、/data/NameChangeEvent、/data/ChangeEvents、/event/Name__chn、/data/Name__chn）
• <defaultReplay> 是否严格为 LATEST 或 EARLIEST？
• <errorRecoveryReplay> 是否严格为 LATEST 或 EARLIEST？
• <state> 是否严格为 RUN 或 STOP？（用户创建的订阅不能使用 PAUSE）
• 是否已填写 <label>？
• 是否包含 <version>（例如 67.0）？
• 是否未包含只读字段（<id>、<createdDate>、<namespacePrefix>）？
• 文件名是否与 DeveloperName 完全一致？

---

输出要求

• 创建 / 更新：managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml——这是唯一需要生成的文件
• 删除：提供删除文件并通过 destructiveChanges.xml 部署的说明
• 读取：显示现有文件内容

---

跨技能集成

需求	委派给
创建订阅所用的平台事件通道（__e）	generating-platform-event 技能
通过 Flow（流程自动化）订阅	generating-flow 技能
将元数据部署到组织	deploying-metadata 技能

---

参考文件索引

文件	阅读时机
assets/managed-event-subscription-template.xml	生成任何新订阅之前——以此作为起始结构
references/topic-name-formats.md	设置 <topicName> 时——涵盖平台事件、更改事件和自定义通道
references/update-constraints.md	更新工作流期间——检查创建后哪些字段不可变
references/delete-guide.md	删除工作流期间——查看破坏性更改部署流程