using-salesforce-archive

Salesforce Archive

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

范围

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

---

所需输入

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

• 操作意图：搜索、查看、取消归档、分析、遮蔽、RTBF、存储检查或作业状态/日志查询。
• 目标 sObject（sobjectName）：搜索和取消归档时必填。
• 筛选条件：搜索和取消归档需要 sobjectName + 至少一个筛选条件。
• 下载日志所需信息：已完成且会生成日志的作业的 requestId（ArchiveActivity Id，前缀为 8qv…），以及 reportType = 该活动的 Type。

前置条件（如果调用返回权限不足错误，请确认这些条件或告知用户）：

• 组织必须已启用 Salesforce Archive（组织权限 TrustedServicesArchive / TrustedServicesArchiveBt）。每项操作首先都会检查此条件。
• 除组织级检查外，每项操作还需要特定的用户权限——请参阅下方的权限表。不存在统一的“归档管理员”角色；访问权限按功能划分。

---

权限

每项操作首先要求组织已启用 Salesforce Archive（hasTrustedServicesArchive = OrgPermissions.TrustedServicesArchive || TrustedServicesArchiveBt）。除组织级检查外，每项功能还需通过不同的用户权限检查。如果用户无权执行某项操作，调用会返回“not permitted”错误——请根据下表将错误与缺少的权限对应起来。

操作	所需用户权限
search-archived-records、get-search-archived-records-next-page	ViewSearchPage（Archive Search）——Connect 搜索端点会执行全局搜索路径，该路径受 Archive Search 权限控制，而非 ViewArchivedRecords
search-archived-records-with-sharing-rules（Agentforce）	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）

权威来源：trusted-services-archive-connect-impl 中的 Connect API 资源类 → TrustedServicesArchiveSdkImpl 权限检查 → TrustedServicesArchive.accessChecks.xml。请注意，search-archived-records 会路由到 performArchiverGlobalSearch（受 canRunArchiveSearch = ViewSearchPage 控制）；单独的 Apex-SDK searchArchivedRecords() 方法受 ViewArchivedRecords 控制，但 Connect API 搜索端点不会使用该方法。

---

工作流

一个任务中的所有步骤都必须依次执行。首次处理某个区域时，先阅读引用的文件。

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. 构造并发送调用 — 严格遵循契约。对于搜索，提供 sobjectName + 至少 1 个筛选条件；对于日期筛选，使用包含 {field, from, to} 的复数 dateRanges 数组，并提供完整的 ISO-8601 日期时间。

4. 根据正确的信号分支处理 — 某些操作会返回 HTTP 201，并在响应正文中包含成功标志（body.statusCode、body.isSuccess）。请查阅 references/connect-api-operations.md，了解每项操作应以哪个信号为准；切勿假设 HTTP 状态本身就代表成功。

5. 每次写入后都要验证 — 重新读取状态以确认操作效果（请参阅下方“写入后验证”表）。异步操作（analyzer、RTBF、masking）会返回一个必须轮询的请求 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 + 至少 1 个筛选条件	控制器会以“Search must be based on at least 1 field”拒绝未筛选的请求 — 不允许对整个对象执行操作。
日期筛选必须使用完整的 ISO-8601 日期时间（2020-01-01T00:00:00Z）	仅包含日期的值（2020-01-01）会因字段类型为 xsd:dateTime 而返回 400 JSON_PARSER_ERROR。
搜索使用复数数组 dateRanges；取消归档使用单数 dateRange	这是两个端点上确实不同的字段；使用错误的格式会静默丢弃筛选条件，或返回 400。
当 scroll_id == "-1" 时停止分页	使用 "-1" 调用 get-search-archived-records-next-page 会返回 500。
下载日志时，requestId 必须是实际的 ArchiveActivity Id，reportType 必须是该活动的 Type	后端会根据活动记录解析日志；reportType 不匹配时不会返回日志。
切勿使用已弃用的查询接口	global-search-by-id、get-global-search-results 和 view-archived-records 已弃用，且没有后续替代接口，目前会返回 500。请改用 search-archived-records（+ next-page）。
无法检索已排除的对象	Feed、History、Relation、Share 不支持搜索；无法通过此 API 检索 Files/Attachments — 不要承诺可以检索。
通过 SOQL/Connect 查询 ArchiveActivity，绝不要使用 Flow	ArchiveActivity 的 isProcessEnabled=false，因此在其上使用 Flow“Get Records”元素会失败，并显示“你无法在 Flow 中获取 ArchiveActivity 记录。”

---

注意事项

问题	解决方法
将 HTTP 201 视为成功	多个操作会返回 HTTP 201，但结果体中的操作结果可能并非成功。应根据 body.statusCode（搜索）或 body.isSuccess（with-sharing-rules）进行分支判断，而不是依据 HTTP 状态码。
将 run-analyzer.isRunning 用作信号	它始终为 null；该端点只会填充 message。应轮询 get-analyzer-report 来确认是否完成。
search-archived-records-with-sharing-rules（Agentforce）的筛选条件是数组	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	遵循端到端监控流程时：查找失败/进行中的作业，然后下载其日志