platform-trust-archive-manage

Salesforce 归档

通过 Salesforce Archive（也称为 Trusted Services Archive）的 Connect API 和 ArchiveActivity 作业元数据对象进行操作。本技能涵盖如何搜索和恢复归档记录、运行分析器、处理 RTBF 擦除和 PII 屏蔽、检查存储空间，以及最容易被忽略的部分——如何从 ArchiveActivity 读取归档作业状态，并使用作业的 Id + Type 下载其日志。

范围

• 包含：调用 /platform/data-resilience/archive/ 下的 Archive Connect API 操作；通过 SOQL/Connect 查询 ArchiveActivity 对象；将作业的 ArchiveActivity 记录与其日志下载端点关联起来；每项异步操作执行写入后验证。
• 不包含：定义归档策略 / ArchivePolicyDefinition 元数据；构建 UI；对归档数据生成 Flows（ArchiveActivity 无法通过 Flow 查询——请参阅注意事项）；与此附加组件无关的通用备份/导出工具。

---

必需输入

操作前请收集或推断以下信息：

• 操作意图：搜索（也可通过此操作查看归档记录）、取消归档、分析、屏蔽、RTBF、存储检查，或作业状态/日志查询。
• 目标 sObject（sobjectName）：搜索和取消归档时必需。
• 筛选条件：搜索和取消归档都要求提供 sobjectName + 至少一个筛选条件。
• 下载日志时：已完成且会生成日志的作业的 requestId（ArchiveActivity Id，以 8qv… 开头），以及 reportType = 该活动的 Type。

前提条件（如果调用返回无权错误，请确认或告知用户）：

• 组织必须已启用 Salesforce Archive。所有操作首先都受此条件限制。
• 除组织级限制外，每项操作还要求拥有特定用户权限——请参阅下方的权限表。不存在单一的“归档管理员”角色；访问权限按功能划分。

---

权限

每项操作首先都要求组织已启用 Salesforce Archive。除了组织级限制外，每项功能还受不同的用户权限限制。用户无权执行的调用会返回“not permitted”错误——请根据下表将错误与缺少的权限对应起来。

操作	所需用户权限
search-archived-records、get-search-archived-records-next-page	ViewSearchPage（Archive Search）——不是 ViewArchivedRecords
search-archived-records-with-sharing-rules	ViewArchivedRecords
unarchive-records	UnarchiveSdk
forget-archived-records（RTBF）+ get-rtbf-status	Rtbf
mask-archived-records + get-masking-status	Rtbf（屏蔽使用同一项 Rtbf 权限——不是单独的授权）
run-analyzer、get-analyzer-report、get-archive-storage-used	ArchiveAnalyzer
get-execution-details-stream-url、get-failed-records-stream-url	ViewActivitiesPage（Archive Activities）

---

工作流

任务中的所有步骤都必须按顺序执行。首次处理某个部分时，请先阅读其中引用的文件。

1. 确定操作并阅读契约 — 不要依赖对 Archive API 的一般了解，因为它的契约并不直观。加载 references/connect-api-operations.md，了解每个 Archive Connect API 操作的准确请求／响应格式、必需输入和各操作的注意事项。请在构造任何调用之前完成此步骤（例如，dateRanges 是复数还是单数、使用 isSuccess 标志还是 HTTP 状态码、url: null 表示没有日志）。

2. 对于任务状态／监控，请阅读数据模型 — 当任务涉及归档任务、失败、进度、计数或日志时，请加载 references/archive-activity-entity.md，了解 ArchiveActivity 字段参考及其与 Connect API 的关联方式。通过 SOQL 或 Connect 查询 ArchiveActivity，不要使用 Flow。有关完整的端到端示例（查找失败／进行中的任务，然后提取其执行详情和失败记录日志），请加载 examples/monitor-failed-jobs.md。

3. 构造并发送调用 — 每个操作都是一个 {method, path, body} REST 调用。使用环境提供的任何 Connect／REST API 工具发送调用（例如，调用 Connect／REST API 的 MCP 服务、sf CLI 或其他 REST 客户端）。两条路径规则至关重要（每项操作的完整契约见 references/connect-api-operations.md）：

   • 此技能中的操作名称不是 URL 路径。 search-archived-records、unarchive-records 等是标签；切勿将它们放入路径。请使用下方的短路径字面值（均相对于基础路径 /platform/data-resilience/archive）。将操作名称作为路径段发送（例如 /…/archive/search-archived-records）会返回 404。
   • 路径到 /platform/data-resilience/archive/… 为止——不包含 /connect 段，即使这是 Connect API。这里的 404 / NOT_FOUND 表示路径错误，而不是 Archive 已停用——在判定缺少附加组件之前，请先修正路径。

   操作	方法 + 路径	备注
   搜索归档记录	POST /search	需要 sobjectName + 至少 1 个筛选条件
   搜索下一页	GET /search/next/{scrollId}	当 scroll_id == "-1" 时停止
   使用共享规则搜索	POST /search/with-sharing-rules	使用 filtersJson 对象映射
   取消归档记录	POST /unarchive	sobjectName + 筛选条件
   运行分析器／报告	POST /analyzer/run · GET /analyzer/report
   忘记／RTBF + 状态	POST /rtbf · GET /rtbf/{requestId}
   脱敏 + 状态	POST /mask · GET /mask/{requestId}
   已用存储空间	GET /storage/archive-used
   执行详情／失败记录日志	GET /log/execution-details-stream-url · GET /log/failed-records-stream-url	查询参数 requestId、reportType

   使用 sf CLI 时，请在路径前加上 /services/data/v67.0；某些 MCP／REST 工具接受裸路径并自行添加版本号（因工具而异——请参阅参考文档）。然后遵循契约：搜索时提供 sobjectName + 至少 1 个筛选条件；按日期筛选时，使用包含 {field, from, to} 的复数 dateRanges 数组，并提供完整的 ISO-8601 日期时间。

4. 根据正确的信号判断 — 某些操作会返回 HTTP 201，但成功标志位于响应正文中（body.statusCode、body.isSuccess）。请阅读 references/connect-api-operations.md，了解每个操作应依据哪个信号判断；切勿假设仅凭 HTTP 状态码就能确定成功。

5. 每次写入后都进行验证 — 重新读取状态以确认效果（请参阅下方的写入后验证表）。异步操作（分析器、RTBF、脱敏）会返回请求 ID，必须轮询该 ID。

---

写入后验证

本次写入后	通过以下方式确认
run-analyzer	轮询 get-analyzer-report，直至报告已填充
unarchive-records	重新运行 search-archived-records——确认记录已离开归档
forget-archived-records（RTBF）	使用返回的 request_id 轮询 get-rtbf-status
mask-archived-records	使用返回的 request_id 轮询 get-masking-status

---

规则 / 限制

限制	原因
搜索和取消归档需要 sobjectName + 至少一个筛选条件	不带筛选条件的请求会被拒绝，并返回“Search must be based on at least 1 field”——绝不允许对整个对象执行操作。
日期筛选条件必须是完整的 ISO-8601 日期时间（2020-01-01T00:00:00Z）	仅包含日期的值（2020-01-01）会返回 400 JSON_PARSER_ERROR，因为该字段的类型是 xsd:dateTime。
搜索使用 dateRanges（复数数组）；取消归档使用 dateRange（单数）	这两个端点使用的确实是不同字段；使用错误的格式会静默丢弃筛选条件或返回 400。
当 scroll_id == "-1" 时停止分页	使用 "-1" 调用 get-search-archived-records-next-page 会返回 500。
下载日志时，requestId 需要使用真实的 ArchiveActivity ID，reportType 需要使用该活动的 Type	后端通过活动记录解析日志；reportType 不匹配时不会返回日志。
排除的对象无法检索	Feed、History、Relation、Share 无法搜索；无法通过此 API 检索文件/附件——不要承诺可以检索。
通过 SOQL/Connect 查询 ArchiveActivity，绝不要使用 Flow	ArchiveActivity 的 isProcessEnabled=false，因此在其上使用 Flow“Get Records”元素会失败，并提示“You can't get ArchiveActivity records in a flow.”。

---

注意事项

问题	解决方法
将 HTTP 201 视为成功	多个操作会返回 201，但结果状态在响应正文中。应根据 body.statusCode（搜索）或 body.isSuccess（with-sharing-rules）进行分支判断，而不是依据 HTTP 状态码。
将 run-analyzer.isRunning 用作信号	它始终为 null；该端点只会填充 message。应改为轮询 get-analyzer-report，以确认操作已完成。
将 search-archived-records-with-sharing-rules 的筛选条件设为数组	filtersJson 必须是 JSON 编码的对象映射 {"Field":"Value"}，而不是 {field,value} 数组；数组形式会返回 isSuccess:false "No valid filters provided"。
因状态码为 201 而认为日志 url 一定存在	get-*-stream-url 返回 {url}；url: null 表示未解析到日志。务必检查 url != null。
误读 get-archive-storage-used	usedStorage[]/availableStorage[] 是按位置对应的并行数组：索引 0=组织 DATA，1=组织 FILE，2=归档 RECORDS，3=归档 FILE。availableStorage[2]/[3] 始终为 0（归档层不计量）——这表示“未跟踪”，而不是“已满”。
期待在 Flow 中使用 ArchiveActivity	它未启用 Flow（isProcessEnabled=false）。请使用 SOQL/Connect/Reports。
达到取消归档上限	每个请求最多处理 ≤1000 条匹配记录，且每个组织每小时最多 ≤50 个请求；每条匹配记录的整个归档层级都会被恢复。
达到 RTBF/遮蔽上限	criteria 最多 ≤10 个条目（每个对象一个）；每天最多 ≤10,000 条根记录（RTBF 和遮蔽共用）；遮蔽不可逆。RTBF 和遮蔽均受同一 Rtbf 用户权限控制。

---

输出预期

这是一项知识/API 技能——它会生成 API 调用及对其结果的解读，以及针对 ArchiveActivity 的 SOQL。它不会生成可部署的元数据。每项任务的交付内容：正确的操作调用、恰当的成功信号分支判断，以及写入后验证的确认结果。

---

参考文件索引

文件	阅读时机
references/connect-api-operations.md	构造任何 Archive Connect API 调用之前——完整的逐操作契约、成功信号和限制
references/archive-activity-entity.md	处理任何作业状态／失败／进度／日志任务时——ArchiveActivity 字段参考，以及它与日志下载端点的关联
examples/monitor-failed-jobs.md	遵循端到端监控流程：查找失败／进行中的作业，然后下载其日志