integration-eventing-subscription-configure

管理 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，请询问用户；不要根据标签推导。
2. 确认主题存在——继续前，请用户确认该事件通道已存在于组织中。请勿自行生成平台事件对象——这超出此技能的范围。如果用户表示该对象尚不存在，请停止操作，并指引用户先使用 platform-custom-object-generate 技能创建，然后再返回此处。
3. 读取模板——加载 assets/managed-event-subscription-template.xml，将其用作起始结构。
4. 生成文件——生成 managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml，并填入用户提供的值。
5. 验证——在展示输出前，运行下方的检查清单。
6. 指导用户进行订阅——部署后，可使用 DeveloperName 或记录 Id 来识别 Pub/Sub API ManagedSubscribe RPC 调用所需的订阅。要获取 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）	platform-custom-object-generate skill
通过 Flow 订阅（流程自动化）	automation-flow-generate skill
将元数据部署到 org	platform-metadata-deploy skill

---

参考文件索引

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